Internationalization (i18n) Standards

Note: This page is a work in progress.

The internationalization of our code is a work in progress, as is the development of our i18n standards. The standards may not reflect what is currently in the code base. We will do our best to keep this page up-to-date with our current standards, but if you're unsure what method to use, please ask! Similarly, please get in touch if you have suggestions. You can comment on a relevant pull request or use the mailing list address on the bottom of this wiki page.

While it is in no way expected, we are very grateful when contributors i18n existing code their pull requests touch. (However, if your pull request is particularly large, it may be best to refrain from doing so and making it bigger.)

• Use double quotes and parentheses in view files. Code should be formatted like <%= t(".key") %>. The service we use removes quotation marks in the locale file, so they are not necessary there.
• Use variable interpolation. If you have a sentence with a variable in it, use interpolation rather than multiple strings. For example, <p>Hi, <%= @user.login %>!</p> can be replaced with <%= t(".greeting", name: @user.login) %> in the view, while the locale file would contain greeting: Hi, %{name}!.
  • If the variable represents a hyperlink, its name should end with _link. This helps our translators identify links and the linked text. For example, <p>If you have questions, please <%= link_to("contact Support", new_feedback_report_url) %>.</p> can be replaced with <p><%= t(".questions", support_link: link_to(t(".support", new_feedback_report_url)).html_safe) %></p>. Note that the variable is the key for the linked text (support) plus the suffix _link.
  • If the variable represents a URL, its name should end with _url. Particularly with mailers, this ensures links and URLs have distinct keys. For example, If you have questions, please contact Support: <%= new_feedback_report_url %>. can be replaced with <%= t(".questions", support_url: new_feedback_report_url) %>.
• Use lazy lookup.
• Keep HTML in the view files. This will reduce the risk of encountering issues with an email's markup when the locale files are automatically updated.
• Keys should be descriptive and not be numbered sequentially. Avoid key names like part1 or para1. If you have a five-paragraph email, with each paragraph called para1, para2, and so on, when you insert a new paragraph between first and second paragraphs, it will require the keys for existing paragraphs to be renumbered. This will require our Translation team to reenter the text for all of those paragraphs in every language.
• Update the key name when modifying text. If the key is not modified, changes to the text may not be brought to Translation's attention, or old versions of the text may be included in the pull requests our translation tool exports, reverting desired changes.