Translate YAML files

🔗What is a YAML file?

YAML (.yml, .yaml) stands for “YAML Ain’t Markup Language™”. YAML files are documents that can be used as language files, typically used by Ruby on Rails and Laravel applications.

WebTranslateIt is a software localization platform that can help localize YAML files.

YAML files come in 4 different flavours:

• Classic YAML
• r18n
• No Definition
• Hugo YAML

If you uploaded a file in one flavour and update that file using a different flavour you will get an error message. You will need to create a new file using that new flavour. that the language file you uploaded uses a different flavour.

Similarly, uploading a Classic YAML file with a language root that does not correspond to the current file language (for instance uploading a file with fr language root to the es language) will raise an error.

🔗“Classic YAML” Flavour

It includes a language root which defines the language of the file. Pluralization is possible using the reserved sub-keys: zero, one, two, few, many, other. These plural keys will be imported as plural segments. It is notably used by the i18n gem included in Ruby on Rails.

en:
  symbol:
    anonymous: "Business"
    :yes: "Yes"
    :no: "No"
    bacon:
      one: "1 bacon"
      other: "{{count}} bacons"

🔗r18n YAML flavour

This YAML file adds types (filters) to the classic ruby .yml file. It is used by the r18n gem.

hi: !!markdown
  Hi, **people**!
greater: !!escape
  1 < 2 is true
log:
  signup: !!gender
    male: Он зарегистрировался
    female: Она зарегистрировалась
user:
  edit: Edit user
  name: User name is %1
  count: !!pl
    1: There is 1 user
    n: There are %1 users

WebTranslateIt can use a few filters: proc, pl, String, R18n::Untranslated, escape, html, markdown, textile and gender. Please contact Support if you need another filter.

🔗“No Definition” YAML Flavour

It is used by some PHP i18n libraries. These files are flat and do not start with a language root defining the language.

segment1: "translation1"
segment2: "translation2"
segment3: "translation3"

🔗“Hugo YAML” Flavour

It is used by the Hugo Framework.

- id: still_need_help
  translation: "Still need help?"

- id: get_in_touch
  translation: "We’re here to help. Get in touch and we’ll get back to you as soon as we can."

- id: contact_support
  translation: "Contact Support"

- id: copyright
  translation: "Copyright"

- id: all_rights_reserved
  translation: "All rights reserved."

- id: help_center
  translation: "Help Center"

- id: search_manual
  translation: "Search Manual"

- id: getting_started
  translation: "Need help getting started or having trouble configuring a device?"

🔗Plural rules

You will notice that plural keys such as “one” aren’t editable in the Chinese interface. This is no mistake, this is due to the fact that the “one” rule doesn’t exist in the Chinese language, so it doesn’t make sense to have one.

For an in-depth explanation about plural rules, visit Understanding Plural Strings

In English, we have our well-known plural rules “one” and “other”:

0 dogs # Uses “other” rule
1 dog  # Uses “one” rule
7 dogs # Uses “other” rule

The word “dog” changes depending on the quantifier.

In Chinese words don’t change depending on the quantifier like most languages do. They would say something like:

0 dog # Uses “other” rule
1 dog # Uses “other” rule
2 dog # Uses “other” rule
7 dog # Uses “other” rule

The plural rules are defined by CLDR, which has documented all the known rules.

Now here’s the thing: The Ruby on Rails framework only knows how to handle English plural rules (one/other) which works for most occidental languages. It works for German for instance, but works badly for French and it’s really not adapted for Chinese, Arabic, Russian or Polish. You need to use the pluralization back-end.

🔗Using the pluralizer back-end in your Rails application:

1. Create a config/initializers/pluralization.rb file in your app, and copy/paste the following code to add the pluralization backend:

   require "i18n/backend/pluralization"
   I18n::Backend::Simple.send(:include, I18n::Backend::Pluralization)
   

2. Download this plurals.rb file, which is part of the i18n gem and place the file under the config/locales/ directory.

3. If necessary, rename the locales key names to suit your application’s needs. For instance, if you use the zh-CN locale code instead of zh, rename the zh key to zh-CN in the plurals.rb file.

4. Restart your application. Rails will be able to create plural phrases using the correct plural rules for Chinese and other languages.

🔗“no”, “yes” imported as boolean in WebTranslateIt?

This is a question that comes up often. You have keys that are named yes or no and you noticed they got imported as a true or false value. What is happening?

YAML strings are typed, which means some keys are cast into a specific type. For instance, the number 1 is cast into an Integer, a Date is cast into a Date and the word false is cast… into a boolean. Up to here everything makes sense.

Now, YAML has defined shorthands for booleans, like no, n, off, yes, y, on, which are cast into booleans. The words no and off are parsed as false, the words on and yes are parsed as true. You can read more about it in the YAML specification regarding booleans.

If you need to use one of these shorthand booleans as a string, wrap it around quotes. For example: "no", so the parser will cast it as a string instead of a boolean.

🔗Empty strings

The i18n frameworks using YAML usually include a language fallback. A language fallback is a system that falls back to use the text from the source language if the target text is not present. If a segment is left empty in WebTranslateit we will export it as a nil value (no value) in your language files so that the fallback mechanism can work.

However if you proofread an empty translation in the translation interface the file generated by WebTranslateit will contain that empty segment with a blank value because we consider you intentionally left that segment blank and want a blank text as a translation.

If you want the translation to be nil and proofread, use ~ in the translation box. This segment will be exported as a nil entry.

🔗Type Casting

WebTranslateIt supports Type Casting. That is, if you upload a segment as an String, Array, Integer, Float or Symbol, it will be exported as such.

🔗More Information

• Ruby on Rails Guide on i18n
• A gem for handling gender
• A gem to connect your app to WebTranslateIt API

🔗Related Platforms