Soluling home   Document home

YAML Localization and Internationalization

YAML Localization and Internationalization

YAML (Wikipedia) is a human-readable text format that stores structured data. Many applications store their strings and settings in YAML files. Soluling Desktop and Soluling Cloud support YAML files (.yaml and .yml).

The end of the document contains links to get the full source code of the samples. After reading this document, we recommend reading a tutorial about how to use Soluling.

YAML files

A YAML file contains keys and values. A value can be a string, a number, a boolean, a nested mapping of keys, or a list. Here is the Simple.yml sample file.

one: One
two: Two
sub:
  three: Three
  four: Four

Soluling localizes the string values. The keys are not localized. They are the IDs of the strings, and nested keys such as sub appear as items in the project tree. Soluling supports all the common YAML structures:

If the root key of the file is a language code (e.g., en:), the file is a Ruby on Rails resource file, and Soluling uses the Rails parser by default.

Localized YAML files

By default, Soluling writes the localized file into a language subdirectory next to the original file. The Finnish file of Simple.yml is fi\Simple.yml.

---
one: Yksi
two: Kaksi
sub:
  three: Kolme
  four: Neljä

Soluling writes each translation in the style of the original value: a quoted string stays quoted, a | or > string stays a block string, and a flow style mapping or list stays on one line. Here is the original multi.yml sample and its Finnish file.

long: |
  First line
  Second line
white: >
  First line
  Second line
simple: Value
---
long: |
  Ensimmäinen rivi
  Toinen rivi
white: >
  Ensimmäinen rivi Toinen rivi
simple: Arvo

If a translation would be read as another data type, such as true or 1, Soluling quotes it so that it stays a string. Soluling also adds the --- document start, and it does not copy the comments of the original file.

Other data types

By default, Soluling localizes only strings. A YAML file can also contain other kinds of data:

boolean1: true
integer1: 1
float1: 1.2
data1: !!binary iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAYAAACqaXHe...

A !!binary value is base64 encoded binary data, such as an image. To localize booleans, numbers, or images, check them on the Data types sheet, or select the items that you want to localize on the Items sheet. The Datas.yml sample contains all these data types.

Desktop process Desktop process

  1. Start Soluling. Drag the YAML file (e.g., Simple.yml) onto Soluling or click the New from File or Files button and select the file.
  2. If Soluling asks what kind of file it is, select YAML file and click OK.
  3. Project Wizard appears. Select the original language and the target languages, for example, Finnish, and complete the wizard.
  4. Translate the project.
  5. Choose Home | Build All to build the localized YAML files, for example, fi\Simple.yml.

When you change the original YAML file, open the Soluling project and choose Home | Scan. Soluling keeps the existing translations, and you only translate the strings that were added or changed.

Cloud process Cloud process

With Soluling Cloud, you localize the YAML file in your browser: upload the file, translate it in Translate, and download the localized files. You need a Soluling account. See the available Cloud plans.

Create a project

  1. Sign in at www.soluling.com and open Cloud > Dashboard for Projects, Users and Terminology.
  2. Click Add a new project, then Select files and pick the YAML file (e.g., Simple.yml), or drag and drop the file onto the page. Click Create.
  3. On the next page, check the project's Name. It defaults to the file's name.
  4. Set the Original language to the language of the file, for example, English.
  5. Under Target languages, check the languages you want to translate to, for example, Finnish and German.
  6. Under Source type, select YAML file (.yaml, .yml). Select Ruby on Rails resource file only if the file is a Rails locale file.
  7. Click Create. The project appears on the dashboard, and its status changes to Ready once the file has been processed.

Translate the project

Click the project's green Translate button on the dashboard. Translate opens the project, and you can type the translations into the grid. Machine translation suggestions, translation memory, and spell checking are available there. You do not have to finish every language before moving on to the next step.

Get the localized files

  1. In Translate's top bar, click the project's name. It opens the project's Manage page, the same page that the project's Manage button on the dashboard opens.
  2. If you have translated something since the localized files were last built, the page says Localized files need to be built. Click Build localized files and wait until it finishes.
  3. The Files section lists the YAML file with a download button for each target language. Save each localized file where your application reads it, for example, fi\Simple.yml.

Update the project

When you change the strings, upload the new original file, translate what is new or changed, and download the localized files again. On the dashboard, click the project's Update file button (the upload arrow), select the new file or drop it onto the page, and click Update. Existing translations are kept, so you only translate the strings that were added or changed.

The dashboard is one of four ways to use Soluling Cloud. You can also use the SoluCLI command-line tool, Soluling Desktop, or SoluMake, which can run the update and build steps in your build pipeline. See the Cloud tutorial for all of them.

Samples

GitHub and <data-dir>\Samples\YAML contain the following samples. Each .ntp file is a Soluling project that localizes the YAML file into Finnish. The localized files are in the fi subdirectory after you build the project.

File Description Notes
Simple.yml
Simple.ntp
A simple YAML file with strings and nested keys. The same file as the sample used above. Try this first!
multi.yml
multi.ntp
Multi-line strings in | and > styles.  
List.yml
List.ntp
A list of strings.  
fold.yml
fold.ntp
A mapping and a list in flow style, written on one line.  
Datas.yml
Datas.ntp
All YAML data types: plain, quoted, and multi-line strings, booleans, integers, floats, and base64 encoded images (!!binary). The project localizes all of them.  
Sport\Sport.yml
Sport\Sport.ntp
Text and numbers about sports. The project localizes the text into Finnish, German, and Japanese.  

Configuring YAML localization

You create a YAML localization project by adding a YAML file (e.g., D:\Sample\Simple.yml) into your Soluling project. You can configure how to localize your YAML file by selecting the item in the project tree, right-clicking, and choosing the Options menu. A source dialog appears that lets you edit the options. This source uses the following option sheets.

Read more about other data files such as XML, XSL, JSON, YAML, INI, Excel, SVG, TMX, XLIFF, text and binary files.