Design for International Markets

Voice experiences aren’t restricted to a single market. You can publish your experience to additional international markets where Alexa is available.

Localize for different markets

We've all had the experience of reading the instructions for a product made in another country or language that the company translated poorly. It's immediately clear to you due to the odd cadence or poor grammar that the author was not conversant in your own language or culture. Poorly translated and localized content negatively affects the customer’s experience and trust in that product. When you do a poor job translating and accommodating cultural differences, this not only negatively affects your skill, it also slowly breaks trust with Alexa across different markets.

If you want to offer your skill in different international markets, you need to localize the content to fit the language and cultural norms of that marketplace. Even within a country, you can have multiple dialects and cultural differences that you need to account for. Different marketplaces also have different technical requirements set by the laws of that country that you need to consider as well. You need to design your skill to be flexible enough for the translation and cultural requirements per marketplace. You need to consider localization as not simply language translation; it’s a cultural shift in the way Alexa converses with customers.

When you design your experience, you need to explore beyond the native culture and languages of your marketplace. Consider the following when designing your skill:

  • What countries and languages do you want to support and maintain over the lifetime of your skill?
  • What level of translation and localization do you need? Do you have access to a native speaker for your localization work?

Best practices for localization

Write short, complete sentences

Long, complex sentences are difficult to translate, and difficult to understand. Be mindful of long strings of nouns or adjectives, or long sentences that work better as short ones. While a given phrase might seem somewhat long now, it can be three or four times longer in languages with different grammatical structures, such as German or Turkish.

Avoid colloquialisms, puns, or local jargon

These cultural turns of phrase might have no equivalent or could be misconstrued in other languages, regions, or even a specific cultural demographic. Work with translators who are native to the region to help you find equivalent jargon only if it is critical to content of your skill. For example, acronyms like “FAQ” won't translate well. Neither will “9 to 5,”since other countries and regions have different concepts on how long a work day is.

Define and use terms consistently

Be consistent in how you present certain names, terms, or actions in your skill. You might need to provide your translator a definition for the terms you are using so that they can help you find the appropriate term in the translated language.

Review all content for geopolitical inaccuracies or sensitivities Check your skill’s content for culturally sensitive topics or terms that could cause offense. For example, an image in one culture can have a totally different meaning or can be very offensive in another culture. You need to check both the verbal and visual content to make sure you’re not offending your customers in different markets.

Images have special risks you need to consider:

  • Flags (flags are recognized differently by some countries)
  • Maps (boundaries are recognized differently by some countries)
  • People (including gestures, hands, feet, and race)
  • Symbols and icons (national, political, religious, spiritual)
  • Mature and risqué images
  • Cultural inferences of colors, numbers, names, or events

Build in localization

When you build your skill for other marketplaces, consider the following best practices:

  • Use unicode (UTF-8) in your text.
  • Prepare to handle location data by country, such as region or zip code.
  • Plan for input handling changes by language type, due to different linguistic structures.

Don’t build prompt structure into code

Different languages have different word order. A noun phrase is a noun plus optionally adjectives and articles. Grammatical rules in a respective language dictate in which order these words need to come. When a noun phrase (NP) contains dynamic content (variables), do not concatenate it.

Avoid string concatenation in code

Concatenating strings affects both internationalization and localization. While a common coding practice, do not concatenate multiple strings to form a sentence. = Although the strings concatenated together might form an acceptable English sentence, many languages have different grammatical rules. Translators might need to change the order of the words in a sentence, which could be impossible to do if you split a sentence into multiple strings.

Word order by language

Do not concatenate either the subject or the object (code dictates word order). Code the string as one string and let translators shuffle the variables in the string (if either the nouns or adjectives are the variables). In addition, the adjectives and articles need to agree in gender and case with the noun and its function in the sentence (subject or direct/indirect object.)

The following table shows an example of word order differences by language.

Language Subject Verb Object Comments
English The big man eats a delicious red apple. English does not have genders for nouns. Adjectives don't need to change form depending on case (function of the noun in sentence).
German Der große Mann(Masculine article, adjectives in nominative case, masculine) isst einen roten, köstlichen Apfel.(masculine, accusative case) Same NP word order as in English, but in German it doesn't hurt to put a comma between adjectives. The article and adjectives need to agree in gender and case.
Swedish Den stora mannen äter ett gott rött äpple. Definitive article reflected in two places, adjective agreement. Second NP change order of adjectives to sound
French Le gros homme (The big man) mange (eats) une pomme rouge et délicieuse.(an apple red and delicious) Different word order from English.
Japanese 大きくて毛むくじゃらな男の人が Ookikute otokonohito ga 食べています。tabete imasu. おいしそうな赤いりんごをOishisouna akai ringo o The word order in Japanese is different (verb at the end).
Hindi बड़े बालों वाला आदमीBade wala admi खाता हैKhata hai एक लाल स्वादिष्ट सेबek lal swadisht seb Just like Japanese, the word order is different for Hindi and the verb is in the end. Also, there are no article in Hindi (the, a, an).
Spanish El hombre grande (The man big) come (eats) una manzana roja y deliciosa (an apple red and delicious) Different word order from English.

Internationalize visual design

When translators localize an English experience, the customer interface and any other text typically require more space due to the different linguistic structures. As a rule, languages other than English have longer words, longer sentences, and might have larger characters (non-Roman characters). In addition, any data, such as dates or numbers, might take up more space as well.

Use overlays, layers, or callouts with graphics

Just like translating the strings in the UI, you also need to translate any text in a graphic. If text is embedded into a graphic, it becomes much harder and expensive to update the graphic with translated text when the time comes. The best way to avoid dealing with localizing graphics is to minimize using graphics in the first place or to remove text in graphics.

Review all images

Use general images that are appropriate and easily understood in your intended countries and marketplaces. Cultural references may not be global. Even literal imagery can feel foreign. For example, mailboxes and tractors look very different in Japan. If you use general images that can be used for a worldwide audience, you don't have to replace them when you launch globally or across different countries and marketplaces.

Beyond checking to make sure images are appropriate for each culture or country, you also need to make sure if the images are displaying properly in each locale and if the right images are even being displayed. For example, are the translated text overlays displaying properly on the images?

30% Rule

Account for at least 30% more space on your UI components around text. For example, some strings translated from English to German take up to 50% more space. To make sure you have enough space, test your content strings as soon as possible. Give yourself enough time to re-design the UI in case the translated text does not fit.

Line wrap and truncation

Your design should expand to fit the additional lines of translated text without seeming clunky or unreadable, especially for essential items such as navigational elements. If you can’t read the text without scrolling or or truncation, have your translator specify where appropriate truncations should occur. You need to define line wrap and truncation behavior for all layouts by using the text component. Use the maxLines property in the text component to call out text components that limit the number of lines – single line, two lines, etc.

Text labels on buttons

Button labels should be short and concise so that translated versions can still fit in the same layout. If the English version is too long, in translated versions the button elongates, which pushes other UI elements off the screen. The same problem also often occurs for customers that choose to enlarge the UI font size better readability. Don’t put everything into a button. Break it out into body text above the button and keep the action-oriented text of the button short. For example, “Okay” or “Cancel.” If you can, avoid placing multiple buttons on a single row.

Font styles and capitalization

Writers often use font styles like bold, italics, underline, strike-thorough, and capitalization (such as making a label all-caps) in English or other Roman-character languages to emphasize or visually differentiate certain text. When you use capitalization or all-caps, you need to allocate more vertical clearance (line height and spacing) because some languages with heavy diacritics need more room to accommodate uppercase letters with accent and descent than in the same lowercase letters. However, some font styles might break language scripts, such as: Chinese, Japanese, Arabic, Hindi (to name a few) that don’t use bold, italics, uppercase and lowercase. Instead, differentiate your text with formatting such as foreground/background color, quotation marks, visible borders, etc.

Spaces between words

In certain languages, such as Japanese, words do not have spaces between them. This makes it difficult to process tasks like disabling substring matches. Because there is no hyphenation or spaces between words, there is no easy way to programmatically prevent "widows" in GUI displays. For example, the last line of a string might contain only one character.

Multi-line clause

Allow the line to naturally wrap instead, or break the clause in such a way that the parts are grammatically independent. When a single clause is broken into multiple lines, it can cause grammatically incorrect translations. Translators translate each resource independently and the translations, when visually combined, do not make sense or has incorrect grammar. This can also happen when a string has embedded newline ('\n') characters, which translators do not know what to do with and will not translate them. This is because many translation agencies do not see the final on-screen placement of the text while they are doing their work.

Dynamic text elements

If a multi-line clause includes an argument to be substituted dynamically, the translated string as a whole might not make grammatical sense because the placement of the argument is being forced to be at a certain position in the clause. To produce grammatically correct translations for such clauses, the position of the argument within the clause needs to be adjustable. Translating variable text in a grammatically correct way requires knowing the grammatical gender and cases of the text being substituted in (which might not be an information that is available) and require different message template for each potential grammatical gender and case. Instead, try rephrasing the message so the argument or variable element is omitted. If that's not acceptable, try rephrasing into a "subject:predicate-nominal" form. For example, the message "Sort by <title|author|recent>" often appears as a button or other UI control. The verb "sort" and preposition "by" will need to change gender in some languages depending on the dynamic text. Rephrasing into "subject:predicate-nominal" form, "Sort Order: <title|author|recent>" simplifies the implementation for proper localization.

Numbers, dates, times

For date, time, phone number, file size and other general number formatting, follow local custom.

Examples of dates and times:

Language Number Date Month Day Time
EN-US -123,456,789.988 September 7, 2018 Sep Sat 2:32:55 PM
EN-UK -123.456.789,988 7 September 2018 Sep Sat 14:32:55
FR -123.456.789,988 7 septembre 2018 sept. sam. 14:32:55
DE -123.456.789,988 7. September 2018 Sep. Sa. 14:32:55
JP -123,456,789.988 2018年9月7日 9月 土曜日 14:32:55

Different countries have different address field labels and field orders. For example, Japanese addresses start with postal code, then from largest to smallest region (country, prefecture, city, address).

Best practices by locale



Japanese names are ordered differently than English names. The order is last name + first name which is opposite to those in English. Japanese append suffixes to names, most commonly the honorific title "san". Automating this concatenation for names pulled from contact lists or databases generally works, but can fail in various cases. For example, A prompt that says, "Message from Tanaka," should be read "Message from Tanaka-san." There are cases where the <name> field contains "san" or a variant, so that simply embedding "san" into the Japanese prompt can result in duplicate titles. For example, the Japanese word for "mother" is "okaasan," so if you have your contacts list has the word "Mom" in it, automatically appending the "san" will read out as "Message from Okaasan-san."

If your prompt uses first and last names, don't build dependencies based on US English conventions for using first and last names. For example, If you have a prompt that says "Call <name>," Japanese are most likely to say <last name><first name>(+ "san"). If they use one name, the last name is more likely for casual acquaintances and co-workers than first name.

English words in data catalogs

Entity matching accuracy may be a challenge. Japanese liberally intersperses English phrases in movie or book titles, musician or band names, restaurant or building names, companies, etc. These words may be entered in romanized letters (romaji) or a phonetic alphabet called "katakana" (or "kana"). Unfortunately, there are multiple accepted forms of kana representation for certain phrases so you may need to append metadata to your catalogs.


If your visual response contains a list that you sort alphabetically, Japanese words will not sort properly unless you append pronunciation metadata. There are tens of thousands of kanji characters that do not have an intuitive visual sorting methodology, and sorting by sound is unreliable because kanji characters can have multiple pronunciations. All lists that you make should be reviewed for proper visual treatment on Alexa-enabled devices with a screen.


If your prompts contain numeric variables, it might generate TTS errors. Japanese appends specific suffixes to numbers, depending on the word. This is analogous to saying "One loaf of bread" in English. The pronunciation of the number can vary depending on the counter and even the context (for example the characters 1日 are pronounced either "tsuitachi" when referring to the first day of the month, or "ichinichi" when referring to a duration of one day). In general, TTS should handle these issues for you, with the exception of a space is inserted in your prompts between the number variable and the counter term, the TTS will likely generate an error because it will try to read the number separately from the counter.


Similarity of golden utterances in Japanese may overlap in different ways than in English. For example, in Japanese, the same verb is used for "play an artist" and "call a contact" ("Taylor Swift wo kakete" = "Play Taylor Swift," while "Taylor Swift ni kakete" = "Call Taylor Swift").

Yes/no answers

For confirmation prompts such as "xxx, (is that) right?", you should make sure your skill lets customers reply yes or no in different ways. The literal translation "attemasuka" could let them say "attemasu" (that's right), not "hai" (yes) / "iie" (no), which causes error prompts.

Error messages

It is culturally appropriate to have in every error prompt in Japanese (not other languages) to begin with "sumimasen" (sorry), regardless of whether the English version has it or not. The literal translation of "I'm not quite sure how to help you with that" sounds unfriendly or odd. Although error messages are particularly difficult because there are a lot of cases that trigger the error prompts, they need to be proper for all of them.


In Japan, the address order starts from postal code, then largest unit to smallest unit. In addition Tokyo is technically a prefecture (equivalent to state) due to its size. As a result, prompts that use city and state information in the US may have unintended results in Japanese (for example, asking for the weather in Tokyo will generate an error prompt asking you to be more specific, in the same way that asking for the weather in Texas would).

Units of measure and time

  • Use the metric system.
  • In Japan, both the twelve-hour clock and the twenty-four hour clock (military time) are used. Trains, for example are typically listed in 24-hour time, but colloquially you are more likely to hear someone say, "Meet me at three PM" than "Meet me at fifteen hundred".
  • Japanese represent months and dates with a number and counter, e.g., months are 1月、2月、3月… and dates are 1日、2日、3日…
  • Japan has a parallel year calendar based on the Emperor's reign. For example, 2018 is often represented as "Heisei 30" in official sources of news or documentation. The current Emperor is retiring next year, so there will be a new imperial reign name that will be announced. That said, most Japanese are comfortable also using the western calendar.