Internationalization

Make commerce better for everyone by building interfaces that work everywhere. These guidelines will help you design, write, and build products that can be used in every part of the world.

We want our merchants to experience Shopify in a way that’s appropriate and meaningful to them, no matter where they are in the world.

We aim to build one experience that works for all merchants in all of our markets. However, when a certain experience doesn’t fit a specific market, we should tailor it.


Definitions

Internationalization

Building your product and interface so they can be used in different locales. This includes creating flexible interfaces that allow for text expansion and changes to word order.

Localization

Adapting your product and interface for different locales to make them a good cultural fit. This includes adapting features, changing visuals, and translating text.

Translation

Converting text from one language to another. Not to be confused with localization, translation is just one part of localizing a product.

Locale

A linguistic region defined by both its language and country. Examples: French-France (fr-FR); French-Canada (fr-CA); Portuguese-Brazil (pt-BR).


Plan for text expansion

When interfaces are localized, the content will often expand in length. In most languages, text is up to 50% longer on average than English, and some languages, such as Japanese, take up more vertical space. Your interface needs to be flexible enough to accommodate these kinds of text expansion.

Do

Good example of wrapped text

Set text to wrap within components in case it expands beyond the width of the component.

Don’t

Bad example of unwrapped text

Don’t leave text unwrapped. It might overlap the edges of the component when translated.

Tips

  • Always assume the worst-case scenario for text length, especially on mobile and in layouts such as tables and columns.
  • Pay particular attention to content elements such as labels that only have a few words. They can expand up to 200%.
  • Always set text to wrap when it expands. It should never truncate.
  • Be especially careful when laying out elements horizontally. Check them on a small mobile screen with expanded text.
  • Our components are designed to be expandable, but you should still test them in your designs and builds. You can fill your builds with expanded text by using the pseudotranslation tool - simply add ?pseudotranslation=1 to the end of the URL in your browser.

Plan for changes in word order

Word order can change dramatically in translation. If the layout and functionality of your interface is dependent on a certain word order, it’s likely to break when localized.

Do

Good example of avoiding sentence-based UI

If content elements need to stay in a certain position on the page, implement them as separate labels, outside of sentences.

Don’t

Bad example of sentence-based UI

Don’t place elements with a fixed position inside a sentence. The order of this sentence would often need to change in translation, which is impossible to do if the interface is built this way.

Do

Good example of link outside sentence

When including links in body text, only use a single term or a small part of a phrase as the link.

Don’t

Bad example of link within sentence

Don’t use full phrases as links. Word order changes might break the link into several parts when translated.

Tips

  • Assume the word order of every sentence in your interface will change when translated.
  • Avoid splitting one sentence into several strings, known as concatenated strings. If you use concatenated strings, translators won’t be able to change the word order and their translations won’t make sense.
  • If you need a content element to stay in a certain position in the interface, place it outside of the sentence. This means it will be independent of word order and won’t change position when translated.

Plan for cultural differences

Merchants in each locale have different cultural sensibilities. Use visuals, content, and interface formats that are useful and meaningful to merchants in all parts of the world.

Do

Good example of text fields

Adapt text fields to match cultural conventions. For example, provide a Prefecture field for Japanese addresses.

Don’t

Bad example of text fields

Avoid forcing North American formats on everyone, such as text fields that assume first name is the given name and last name is the family name. In many cultures this is not the case.

Tips

  • When using photos, illustrations, icons, or emojis, make sure the visuals you’re using are not offensive or culturally insensitive. If you’re unsure about a visual you’re using, research it or ask someone with local knowledge.
  • When naming features, be mindful of connotations in other cultures, especially for evocative names and acronyms. Find out more about Naming.
  • Avoid colloquial words, idioms, and references to popular culture. It’s difficult to translate them in a meaningful way.
  • In some cultures, a person’s given name comes first, whereas in other cultures the family name comes first. Let merchants choose how they want to enter, read, and sort names, especially in text fields and lists.
  • Many types of information, such as addresses, dates, numbers, and currencies, are shown in different formats in different locales. For example, some locales display currency symbols before the number, others display them after. Make sure these can be translated appropriately. Shopify teams can have these adapted automatically for each locale by using the relevant helper.

Localizing with Polaris components

  • Some components are being “pre-localized” so they automatically adapt for different locales. Use these components to ensure your interface adapts correctly.
  • When designing with a pre-localized component, test the localized versions to make sure it still works with the rest of your interface.
  • If you need a certain component to adapt, but it hasn’t yet been pre-localized in Polaris, you can open a feature request in GitHub.