Translate a YAML file into English

What changes when a YAML locale file becomes English

In a YAML translation file, only the values are user-facing text. Whatever your source language, English is usually compact: from French, values shrink by roughly 10 to 15 %, so Enregistrer les modifications becomes Save changes. Buttons that overflowed in the source rarely break in English.

Less visible differences matter more:

• Punctuation: French spaces before ? and :, Spanish opening ¿ and German low quotation marks all go; English uses its own quotation marks and no space before punctuation.
• Capitals: English capitalises months and weekdays. In a Rails file, the month_names array moves from janvier or enero to January.
• Apostrophes: English is full of them (don't, you're). Inside a single-quoted YAML scalar they must be doubled: 'Don''t show again'.
• Root key: in Rails or i18n-js, de: or fr: becomes en:; the rest of the tree stays put.

Plurals, variables and formats: the English pitfalls

English has only two plural categories: one and other. If your source is Polish or Russian, with few and many, or French, which also has many, the extra categories have no English counterpart: plurals are adapted to the target language. Note too that English one covers 1 only; zero takes other ("0 messages"), whereas French treats 0 as singular.

Variables such as %{name} and {name} are kept intact, but their position often moves: Hallo %{name}, Sie haben %{count} neue Nachrichten becomes Hi %{name}, you have %{count} new messages. A German sentence ending with its verb is rebuilt in English around the same variables.

Date formats are not translated. A value such as default: '%d.%m.%Y' stays as it is: you will want %d/%m/%Y for a UK audience or %m/%d/%Y for a US one, and that change is yours to make. Check decimal separators too (comma in much of Europe, full stop in English) under keys such as number.format.separator.

British or American English: decide before you start

English is not a single standard: colour or color, organise or organize, cancelled or canceled. One file should stay consistent. Check which spelling is used in the free extract before paying: it shows one paragraph of your file translated at the level you chose.

If your app separates en-GB and en-US, the simplest route is to start from one English file, then duplicate it and adjust the values that differ: spelling, date format and sometimes vocabulary (postcode / zip code, mobile / cell phone). In Rails, the second file's root key then becomes en-GB: or en-US:, which you change yourself.

Register matters as well. English interfaces have no formal and informal "you", and they tend to be more direct than many source languages: Veuillez saisir votre adresse or Bitte geben Sie Ihre Adresse ein simply becomes Enter your address.

What Manuce returns, and what it does not do

You get back the same YAML file, ready to drop into the project: indentation, key order, quotes, comments, line endings, encoding and BOM are preserved. Anchors and aliases (&defaults, *defaults) and | and > blocks are kept, and the root language key is handled for Rails, Symfony, Hugo and i18n-js. Only the values change.

Every translated value is compared with the source: if a %{count} or a tag is missing and the mismatch persists, the source value is kept and the report says so. The report also lists the strings translated and those left unchanged, with the reason.

Not translated: keys, empty values, URLs, email addresses, numbers, colours (#1A73E8), date formats, identifiers and anything marked as non-translatable. The price is based on the words in the values, with keys and tags excluded.

Manuce does not convert date formats for a US audience, and it does not take glossaries or terminology instructions. Nor does it produce certified (sworn) translations, which are irrelevant for an interface file anyway.

Preparing the file and checking the result

• Make sure the source file loads without errors: YAML that is invalid in the source will still be invalid in English.
• Look for values already in English in the source file (Dashboard, Login): they are processed like everything else, so reread them in the result.
• For a product or feature name that must stay as it is, check it in the free extract and then in the delivered file.
• After delivery, reload the file with a YAML parser (YAML.load_file in Ruby, yaml.safe_load in Python), then run the app in English.
• Test plurals with 0, 1 and 2: in English, 0 must show the other form.
• Read the report: any value left in the source language is explained there.

In practice

1. Export the source locale file, for example config/locales/de.yml or messages.fr.yaml.
2. Upload it to Manuce: the quote appears at once, based on the words in the values.
3. Choose a level and read the free extract, paying attention to British or American spelling.
4. Download the English file and the report, then validate the YAML with your parser.
5. Put the file back in the project and test the English interface, plurals included.