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, and adapted for, every part of the world.
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.
Set text to wrap within components in case it expands beyond the width of the component.
Don’t leave text unwrapped. It might overlap the edges of the component when translated.
- 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. Shopify teams can fill their builds with expanded text by using the pseudotranslation tool, available under Account Actions on your test store.
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.
If content elements need to stay in a certain position on the page, implement them as separate labels, outside of sentences.
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.
When including links in body text, only use a single term or a small part of a phrase as the link.
Don’t use full phrases as links. Word order changes might break the link into several parts when translated.
- 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.
Adapt text fields to match cultural conventions. For example, provide a Prefecture field for Japanese addresses.
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.
- 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.