DEV Community

loading...

Six donts of web app internationalization

sapegin profile image Artem Sapegin Originally published at blog.sapegin.me ・3 min read

I wrote these guidelines originally for Wayfair internal frontend documentation. Here’s an adapted and improved version. All examples below are using React and React Intl library but these recommendations are generic for web apps and can be applied with any framework and internationalization library.

1. Don’t concatenate strings

Incomplete phrases are hard or even impossible to translate, because the translators don’t see the whole phrase. Also, the order of parts may be different in other languages.

Merge all related parts of a phrase into a single localization string, and use interpolation for dynamic content, instead of splitting a single sentence into multiple localization strings.

Bad:

<p>
  <FormattedMessage
    id="homepage.firstGreetingText"
    defaultMessage="Hey "
  />
  {name}
  <FormattedMessage
    id="homepage.secondGreetingText"
    defaultMessage=", welcome back!"
  />
</p>
Enter fullscreen mode Exit fullscreen mode

Good:

<p>
  <FormattedMessage
    id="homepage.greetingText"
    defaultMessage="Hey {name}, welcome back!"
    values={{ name }}
  />
</p>
Enter fullscreen mode Exit fullscreen mode

Example: “red pencil” in English would be “crayon rouge” in French (note the reversed order of words).

2. Don’t nest strings

Similar to the previous tip, nested strings are hard to translate because the translators see only part of the phrase.

Keep a complete phrase as a single localization string, and use tag interpolation to add formatting or dynamic elements like links or buttons. This may be different or impossible in your internationalization library.

Bad:

<p>
  <FormattedMessage
    id="landingPage.termsConditionsText"
    defaultMessage="By selection “Purchase” below, you agree to our <a />."
    values={{
      a: () => (
        <a href={TERMS_URL}>
          <FormattedMessage
            id="landingPage.termsConditionsLink"
            defaultMessage="Terms & Conditions"
          />
        </a>
      )
    }}
  />
</p>
Enter fullscreen mode Exit fullscreen mode

Good:

<p>
  <FormattedMessage
    id="landingPage.termsConditionsText"
    defaultMessage="By selection “Purchase” below, you agree to our <a>Terms & Conditions</a>."
    values={{
      a: (...chunks) => <a href={TERMS_URL}>{chunks}</a>
    }}
  />
</p>
Enter fullscreen mode Exit fullscreen mode

3. Don’t hardcode punctuation outside localization strings

Different languages may use punctuation differently: for example, different spacing around characters or even different characters.

Put punctuation inside localization strings, instaed of adding it in the code.

Bad:

<p>
  <FormattedMessage
    id="registration.usernameLabel"
    defaultMessage="Username"
  />
  : <input type="text" />
</p>
Enter fullscreen mode Exit fullscreen mode

Good:

<label>
  <FormattedMessage
    id="registration.usernameLabel"
    defaultMessage="Username:"
  />{' '}
  <input type="text" />
</label>
Enter fullscreen mode Exit fullscreen mode

Example: “Username:” in English would be “Nom d’utilisateur :” in French (note the space before the colon).

4. Don’t reuse translations in different contexts

The same English strings may be translated differently in different contexts, or a translation can be tweaked for a specific page without realizing it would affect other pages.

Create unique localization strings for your features, instaed of reusing phrases that look the same in English in many places.

Bad:

<FormattedMessage id="bookmark" defaultMessage="Bookmark" />
Enter fullscreen mode Exit fullscreen mode

Good:

<FormattedMessage
  id="productCard.bookmarkButtonLabel"
  defaultMessage="Bookmark"
/>
Enter fullscreen mode Exit fullscreen mode

Example: “Bookmark” heading and “Bookmark” button label in English would be “Закладка” and “Добавить в закладки” in Russian.

5. Don’t hardcode pluralization

Many languages have more complicated pluralization rules than English, and have more than two plural forms.

Use your internationalization library pluralization functions, instead of adding s at the end of the word.

Bad:

<p>
  {resultCount > 1 ? (
    <FormattedMessage id="NumberResults">
      {resultCount} dogs found
    </FormattedMessage>
  ) : (
    <FormattedMessage id="NumberResult">
      {resultCount} dog found
    </FormattedMessage>
  )}
</p>
Enter fullscreen mode Exit fullscreen mode

Bad:

<p>
  <FormattedMessage id="NumberResults">
    {resultCount} dog(s)
  </FormattedMessage>
</p>
Enter fullscreen mode Exit fullscreen mode

Good:

<p>
  <FormattedMessage id="search.numberResults">
    {resultCount, plural, one {# dog} other {# dogs}} found
  </FormattedMessage>
</p>
Enter fullscreen mode Exit fullscreen mode

Example: “1 dog, 2 dogs, 5 dogs” in English and “1 собака, 2 собаки, 5 собак” in Russian.

6. Don’t inject HTML into your pages

Injecting HTML from third-parties directly into your pages may break your app or even give hackers the opportunity to get access to your users’ data.

Only send data from the backend and translate text on the frontend, instead of sending already translated text as HTML.

Bad:

<span dangerouslySetInnerHTML={{ __html: message }} />
Enter fullscreen mode Exit fullscreen mode

Good:

<FormattedMessage
  id="reviews.successMessage"
  defaultMessage="Thanks for sharing! You’ve been entered to win a {amount} shopping spree!"
  values={{ amount }}
/>
Enter fullscreen mode Exit fullscreen mode

Bonus: Don’t use "dumb quotes"

This isn’t rally an internationalization issue but still worth mentioning.

Using incorrect typography characters makes our pages look unprofessional.

Use correct typography characters, like quotes, apostrophe or dashes (“”’—), instead of characters that we use in our code ("'-).

Bad:

<FormattedMessage
  id="homepage.lunchCta"
  defaultMessage='Ready to say "lunch!"'
/>
Enter fullscreen mode Exit fullscreen mode

Good:

<FormattedMessage
  id="homepage.lunchCta"
  defaultMessage="Ready to say “lunch!”"
/>
Enter fullscreen mode Exit fullscreen mode

Conclusion

The goal of these best practices is to give translators more context, so they can produce better translations, so your non-English speaking users will have a much better experience. Sometimes a single incorrect or inappropriate translation can prevent a user from understanding the interface and how to use it.

Here are some good resources on internationalization and web typography:

Discussion (1)

pic
Editor guide
Collapse
qm3ster profile image
Mihail Malo

Dumb quotes FTW