Ruby on Rails Localization

The most common library for internationalizing and localizing Ruby on Rails applications is rails-i18n. A detailed guide on how to use it in your Rails applications can be found here: Rails I18n API.

Besides other file formats YAML is the most commonly used format for internationalizing Rails applications. YAML is a human-readable data serialization format. Unlike some other formats, YAML has a well defined standard.


  • Key-value pairs are delimited with colon (:).

  • Values can be surrounded by single or double quotes.

  • YAML has a lot of other rules on how to mark value blocks. Eg. using “key: |” for multi-line values.

  • Rails I18n uses the hierarchical style to structure your file (see example below).

  • Multiple languages are allowed in one Rails I18n YAML file. But this approach is hardly used and we recommend to use one file per language.

  • The first level always has to define the language of the following translations according to ISO_639-1. Lingohub will use the language information from the file content.

  • Comments start with a hash sign (#) and are ignored by all known parsers. But in the Lingohub context, all comment lines are parsed directly preceding a key-value pair (with no blank lines in between) and are treated as translation descriptions or LingoCheck rules belonging to that line.

  • The placeholder syntax is: %{name}, where “name” can consist of multiple non-whitespace characters.

  • Lingohub is aware of parsing array structures.

  • UTF-8 is the default encoding for Rails I18n YAML files.

  • Lingohub is capable to parse both array syntax types (see example below), but cannot guarantee that the same syntax is used when exporting the file.

  • Lingohub cannot guarantee to use the same quoting and escaping as imported when exporting a file, but will always produce a syntactically correct file.


Additional example files can be accessed here.

# this comment is ignored because it is not directly followed by a key-value pair
  # this comment is also ignored, 
  # because it is followed by a key that has children nodes
    hello_user : Hello %{username}
    # comments are treated as translation descriptions 
    # belonging to the key-value pair that follows
    # lingochecks as well
    # lh-check {placeholders:true, terms: Lingohub, min: -5, max:+5}
    welcome: Welcome to Lingohub! this is your %{visit_count} visit.
    # example of an array in YAML
      - Reach billions with your apps!
      - Android, iOS & Co!
      - Clever Github integration!
    another_array: ['one', 'two', 'three'] 
    multi_line: |
      A multi 
      line value


Last updated