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.)

Some locations in the code use the ts helper, which looks like a translation helper but is not one. Instead, use the Rails built-in t helper as documented in the general Rails Internationalization (I18n) Guide.

General Guidelines

• 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_html", support_link: link_to(t(".support"), new_feedback_report_url)) %></p>. Note that the variable is the key for the linked text (support) plus the suffix _link. Note that because the translated text includes HTML (for the link), you need to mark the key as HTML safe by using the _html suffix.
  • 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.
• Consistently format work links and titles in mailers. In HTML emails, use style_creation_link(@work.title, work_url(@work)) to link to works. In text emails, format references to works as "Work Title" (https://archiveofourown.org/works/000). If the work is no longer on the site, e.g., as in deleted work emails, use style_creation_title(@work.title) in HTML emails and "Work Title" in text emails.
• Consistently format collection links in mailers. In HTML emails, use style_link(@collection.title, collection_url(@collection) to link to collections. In text emails, format references to collections as "Collection Title" (https://archiveofourown.org/collections/collection_name). If a word like "collection" or "challenge" follows the collection title, exclude the word "collection" or "challenge" from the hyperlink in the HTML email, but format it as "Collection Title" challenge (https://archiveofourown.org/collections/collection_name) in the text email.

i18n-tasks

We use the i18n-tasks gem to help us manage translations.

Before submitting a pull request with i18n changes, it's a good idea to run the specs that check for missing keys and unused translations and ensure the English locale file is normalized:

 RAILS_ENV=test bundle exec rspec spec/lib/i18n/i18n_tasks_spec.rb

You can also run the associated tasks before running the tests:

 bundle exec i18n-tasks missing -l en -t used,plural # Check en.yml for missing keys
 bundle exec i18n-tasks unused -l en # Check en.yml for unused keys
 bundle exec i18n-tasks normalize -l en # Normalize en.yml

Renaming locale keys

The i18n-tasks gem can be used to easily rename (move) locale keys. To rename locale keys, perform the following steps:

• Uncomment the data write config in config/i18n-tasks.yml line 25.
• Move the locale keys with bundle exec i18n-tasks mv FROM_KEY_PATTERN TO_KEY_PATTERN.
• Turn line 25 in config/i18n-tasks.yml into a comment again.
• Move the locale from config/locales/phrase-exports/en.yml into to correct en.yml files in the config/locales/ subfolders.
• Update the view files to actually use the changed keys.