3 min. read

Dealing with YAML files and their Directory Structure

Michaël Hoste

Michaël Hoste

Founder & CEO

Who is Michaël?

Michaël is the founder of Translation.io. He is always interested in hearing your feedback on the product.

Feel free to get in touch: michael@translation.io

This article is about the way Translation.io deals with YAML files. Whether you prefer YAML over GetText or you use GetText but dealing with a few YAML keys is inevitable, this page is for you!

Since YAML doesn’t guarantee that only a language is contained in a single file, we unfortunately are not able to mirror your source YAML structure.

Init & sync

Initializing your project implies :

  • All .yml files containing keys of your source language will be kept.
  • All .yml files containing keys of your target languages will be grouped into one named translation.LANGUAGE.yml.
  • All localization keys will be separated into localization-specific files. These files are named localization.LANGUAGE.yml.

Let’s see this in details.

translation.xx.yml files contain all the “textual” YAML keys from your project. Once your translators translated them in Translation.io, you can sync and they will be updated. You cannot edit them directly: they will be overridden at each sync.

localization.xx.yml files contain all the non-textual (date formats, booleans, variables) keys that your translators will not understand. We populate them with the correct values for the target languages when initializing the project. These files are not synced with Translation.io. So you can update them manually if you need to. You can also configure other keys to be treated as localization.

Adding new keys

When a new key is needed:

  • Add it to one of your source files.
  • The next sync will send this new key to Translation.io and the key will be added to all target translation.xx.yml files.
  • After the key is translated in Translation.io, one more sync and your application translations will be up-to-date.


Let’s say your project is in en and is translated to fr and es. And you have these files at the moment :

  • config/locales/en.yml
  • config/locales/stuff.en.yml
  • config/locales/en/other.en.yml
  • config/locales/fr.yml
  • config/locales/stuff.fr.yml
  • config/locales/es.yml
  • config/locales/stuff.es.yml

After an init, you will have these files :

  • config/locales/en.yml
  • config/locales/stuff.en.yml
  • config/locales/en/other.en.yml
  • config/locales/translation.fr.yml
  • config/locales/translation.es.yml
  • config/locales/localization.fr.yml
  • config/locales/localization.es.yml

Same file struture for source language and two files per target language for localization.

Published on August 05, 2014
Ready to give it a try? Start your free 7-days trial