Best practices in translating your platform

Posted: October 27th, 2021 | Author: | Filed under: Developers | No Comments »

Translating a platform becomes more important as the market shifts toward globalization and the internet became available even for poor countries. But as a developer it is a challenge to organize the translations in such a way that serves all parties involved in the process.

Let's begin with stories:

  1. as a developer I want to be able to use the same translations for common buttons such as edit, delete, add, etc
  2. as a developer I want to have the translations grouped by a model so I can find them easily when working on a particular feature.
  3. as a developer I want to split the translation by modules/packages/bundles so I can stay focused on a single part of the application when working on it
  4. as a project manager I want to have the translations grouped by business logic so I can give them to a translator then to a reviewer

Possible implementations related to the location of the translation files

Note that <somepackage> is the name of a package/module/bundle and <language> is the language code.

  1. All files under the same translation folder:
    /translations/somepackage.language.yaml
    /translations/anotherpakage.language.yaml
  2. Translations inside the same folder of different packages
    somepackage/translations/language.yaml
    anotherpackage/translations/language.yaml
  3. All files under language-related folders:
    language/somepackage.yaml
    language/anotherpackage.yaml
    – this one opens the possibility of having not only 'yaml translation files' but also entire documents translated and stored here, like emails in both text and html formats.
  4. Nested paths, e.g. the list of translations is made of a sequence of files where the keys in the later files overwrites the first ones.
    translations/messages.language.yaml
    somepackage/translations/messages.language.yaml
    – while is neat for the developer, it may be difficult for the project manager to cover all implications

Possible approaches related to the position of the translation keys inside the files

  1. Use a <global> key for global translations and <model> keys for specifics
    global:
    edit: Edit
    User:
    create_user: Create user
    – the problem here may be that sometimes seems awkward not to place an "invitation" keyword under an "organization" model because the "invitation" is also a model, but in the application it makes sense to relate the invitation to the organization only
  2. Use business logic based on the features implemented (by menus, for example):
    account_management:
    create_user: Create user
    purchased_plan: Purchased plan

Every approach seems to have some advantages and disadvantages, but choosing the proper approach has to be done very early in the project's lifetime and once chosen one stay stick with it in order to avoid frustrations. Which one do you prefer?