I18n Localization Rules (Rails)

Abstract

Managing keys in an efficient way is an important aspect of internationalization in terms of the naming of keys, avoiding duplication of keys and organization of keys.

Rules for localization offer a set of basic rules which can be used during project implementation and by future contributors. Rules for localization will help us to introduce new keys and modify existing one easily.

Style for key naming

Keys can be named using snake_case or camelCase. For long key names snake_case is obviously more readable and shall be used for the naming of keys.

Explicit naming of keys

Rails provide many lookup techniques including lazy lookup which may not help in understanding the purpose of the key completely.

Explicit key names help in understanding the purpose and where it belongs easily. Consequently, keys shall be named as key_prefix/namespace + key_name

Key prefix shall be named according to the context of the current resource or file name in which key will be used. Key prefix for the particular key name can be more than one depending on the level of nesting done for the key name.

Key name shall be named according to the purpose of the key and considering context as well.

Right

t("teachers.main_heading") 

Wrong

t(".main_heading") 

Treating keys as methods

To avoid collisions and duplication of keys, keys shall be treated as methods in a particular namespace or the whole translation file.

Care shall be taken while introducing a new key in a particular namespace of translation. Same key names can be valid but in different namespaces.

Right

en:
  namespace1:
            main_heading: "string1"
  namespace2:
            main_heading: "string2"

Wrong

en:
  main_heading: "string1"
  main_heading: "string2" 

Translation Directory

• we support nested directory structure and advise to follow exact codebase structure. (eg. for app/views/ create config/locales/views to store YAML files)

• Second level nesting should be done following codebase structure. (eg. for app/views/logix create config/locale/views/logix)

• Considering performance factors, further nesting should be avoided as much as possible and a single YAML file for one module, holding translation for one language is advisable. (eg. config/locale/views/logix/en.yml )

Similarly, this can also be followed for other relevant modules.

Module Specific I18n Rules

There can be many other sections but some of the major Rails sections to be localized are as follows -

• Views
• Models
• Forms
• Controllers
• I18n in gems

I18n for general strings and strings repeating throughout the app

General and very specific strings such as delete edit update launch shall be placed by creating YAML file directly at config/locale/en.yml (for the English language)

A similar rule shall also be followed for the strings repeating throughout the app.

I18n in Views

• case1: Module containing only single ERB template or

  Here we use folder name as a top-level namespace and not use ERB template name as a namespace

  For views/about/index.html.erb

  In config/locale/views/about/en.yml

  Right

  en:
    about:
      all_keys present for about page

  Wrong

   en:
     about:
      index:
        all_keys present for about page
  

• Case 2: If a module with multiple ERB templates is present and has many static strings associated with each template.

  Here we use folder_name + template_name as a top-level namespace

  For views/logix/teachers.html.erb and views/logix/contribute.html.erb

  In config/locale/views/logix/en.yml

   en:
     logix:
          teachers:
                  all keys present for teachers page
      
          contribute:
                  all keys present for contribute page
  

• Case3: If a module with multiple ERB templates present and most of the templates are partials for CRUD operations (update, edit, delete )

  Such modules more often have general strings and usually possess fewer strings. Here we use folder name as a top-level namespace

  For views/announcements/_announcement.html.erb

  In config/locales/views/announcements/en.yml

  Right

  en:
    announcements:
                 key-value-pairs

  Wrong

  en:
    announcement_partial:
                        keys for partial
  

I18n in Rails forms

All translations must be placed in config/locale/forms/folder_name/en.yml

For views/announcements/_form.html.erb

In config/locales/forms/announcements/en.yml

en:
  helpers:
    label:
      all labels translations

Rails forms provide suitable helpers for translating different form attributes without the use of translation functions. When translations placed in an appropriate namespace, attributes are translated according to the current locale by Form Helpers.

If submit button of any form uses default strings (eg. update user, create user etc) then we can assign translations to the submit button without using t() in templates and by using helpers

helpers:
       submit:
             create: "create user"
             update: "update user" 

If submit button of forms uses custom strings then we can simply use t() in views and assign string value in YAML templates to translate them.

I18n in controllers

All the translations must be placed in config/locale/controllers/en.yml. As controllers are less prone for static strings of all the controllers placed in a single YAML file under the appropriate namespace.

Namespacing shall be done according to controller_name + method_name

For app/controllers/groups_controller.rb

In config/locale/controllers/en.yml

en:
  groups:
        create:
              key-value pairs