Proposal: Translation keys for the web app

[davidgamez]

Considerations

As Mobility Database serves consumers globally, it’s a great practice to serve the UI and data in local languages to make our service more accessible. As a small organization, having a full-time team of translators in 10+ languages is challenging. In this discussion, we limit the conversation to just the Web UI labels, not the data.

Requirements

• Create a dev process that is “easy” to use for internal and external collaborators.
• Allow text overrides on translated keys
• Integrate the solution to the dev experience

Solutions

Fully automated

Create a script that calls the translate API with the JSON files and publishes them to GitHub. This can be done per branch on PR. We should about direct commits to the main as the QA deployment gets triggers per main pushes.

Pros

• Easier to implement
• No human tasks involved

Cons

• No easy way to override values
• We need to decide how to “commit” the changes to the master or branches
• The lack of human interaction may lead to JSON format issues

Github action + human reviewer

Create a script to translate JSON files. The script is executed on GH actions when files are changed. The script can add a comment to the PR with a zip of the generated files; then the developer should get the files and commit them to git after reviewing them. A variant of this is to always keep the autogenerated files in Git for reference, in this case, the script can commit back the files without the need for an attachment.

Pros

• Allow human override on values and JSON formatting validation

Cons

• Developers need to be more knowledgeable about the process

Local script

Pros

• Easy to use
• Probably the most flexible solution.

Cons

• We cannot share this solution with external collaborators as we would need to share internal credentials.
• Need local setup for translation script vs centralized configuration like Github ones.

Translate text override

In case the text overrides, we can keep a twin file to the original target file with just the keys that are override. This reduces the risk of losing overrides on translation files and keeps a history of community-suggested overrides.
Example:

Source file common.json

{
    "copyToClipboard": "Copier dans le presse papiers", // Hypothetical example the `-` was missing
    "copied": "Copié!",
    "name": "Nom",
    "email": "Courriel",
    "organization": "Organisation",
    "signOut": "Déconnexion",
    "unknown": "Inconnu"
}

Override file common_override.json

{
    "copyToClipboard": "Copier dans le presse-papiers",// Hypothetical example the `-` was missing
}