i18n Style Guide

[razbakov]

What does i18n mean?

• i18n means internationalization, it's just that between first letter and last letter of that word there are 18 letters.
• l10n means localization
• Checkout official documentation of the vue-i18n plugin

Style Guide

• i18n key pattern: <page>.[section].<component>.[attribute]
• camelCase for multiple words

Background

Translation file (en.yml) is in YML format, but it's just replacement for JSON.

What are possible ways to map strings in JSON?

You would probably start with plain object:

{
  "Login": "Login",
  "Logout": "Logout",
  "New post": "New post",
}

And you will create same file for each language, just changing values with translations.

But what if you decide later to change New post to Add post? You will need to change the key in all language files and in all source code files.

Alternative way is to use more abstract keys, that gives you more flexibility. For example:

{
  "login": "Login",
  "logout": "Logout",
  "new": "New post",
}

And what if you now have another feature: Add event? You alternatives are:

1. make complex keys
2. group by meaning

Complex-word keys would be:

{
  "login": "Login",
  "logout": "Logout",
  "newPost": "New post",
  "newEvent": "New event",
}

And what if now you have a login screen, which has a title, subtitle, 2 fields and submit button?
You might do this:

{
  "loginTitle": "Login",
  "loginSubtitle": "Please login to continue",
  "loginSubmit": "Continue",
  "logout": "Logout",
  "newPost": "New post",
  "newEvent": "New event",
}

And what if you have a registration screen which have similar elements?

{
  "loginTitle": "Login",
  "loginSubtitle": "Please login to continue",
  "loginSubmit": "Continue",
  "registerTitle": "Registration",
  "registerSubtitle": "Create new account",
  "registerSubmit": "Start",
  "logout": "Logout",
  "newPost": "New post",
  "newEvent": "New event",
}

As you see translation file grows exponentially. You can make life easier for developers and translators by grouping keys:

{
  "login": {
    "title": "Login",
    "subtitle": "Please login to continue",
    "submit": "Continue",
  },
  "register": {
    "title": "Registration",
    "subtitle": "Create new account",
    "submit": "Start",
  },
  "logout": "Logout",
  "post": {
    "new": "New post"
  },
  "event": {
    "new": "New event"
  }
}

When grouping elements look for similarities, what those elements have in common and how it would scale.

Input element can have label, placeholder, error. Those are attributes of that element, so it make sense to group values by element name, i.e. in our login screen:

{
  "login": {
    "title": "Login",
    "subtitle": "Please login to continue",
    "submit": "Continue",
    "username": {
      "label": "Enter your username",
      "placeholder": "JohnDoe",
      "error": "Username is a required field",
    }
  },
}

But what if there are more error messages later? If we need to add error message for complexity validation (i.e. "Please use numbers, letters, special symbols"). Both are errors, so we would group them under errors.

How does this look in YML?

There multiple ways to describe objects in YML, the one that looks similar to JSON:

login:
  title: Login
  subtitle: Please login to continue
  submit: Continue
  username:
    label: Enter your username
    placeholder: JohnDoe
    error: Username is a required field

More on this topic:

• https://dev.to/omaiboroda/three-ways-to-name-i18n-translation-keys-2fed
• https://medium.com/frontmen/web-internationalisation-i18n-lessons-ive-learned-the-hard-way-438a3e157e0
• https://lokalise.com/blog/translation-keys-naming-and-organizing/
• https://phrase.com/blog/posts/ruby-lessons-learned-naming-and-managing-rails-i18n-keys/

[nelson2411]

Great article!