Loco

Loco is a tool for managing translations. It’s essential for keeping translations across locales current and synchronized by providing a dashboard of progress and delegating admin/translation responsibility.

This manual is tailored for localizing Magento. Adapt for other frameworks as necessary.

Prerequisites

Terminology

So we’re on the same page, this manual uses some phrases that mean almost the same thing in Loco, Magento, and common language — but they mean this:

Term Meaning
Translation Converting from one language to another.
Ex: English to French
Localization Translation on steroids. Converting from a source to variant.
Ex: English to English (US) / English (GB) / French (FR)
Locale A context defined by language (required) and region (optional).
Ex: en or en_US
Source code The string exactly as it appears in code. Localization files convert from source code to a variant locale.
Source locale A neutral context for a language that all variant locales are based on. It’s never exported.
Ex: en or fr
Variant locale A specific context that is localized for one region. Only these are exported.
Ex: en_US or fr_FR

Planning locales

Goals for localization management:

  1. Maintain 100% translation coverage across locales.
  2. Use the fewest locales possible.

Consider these locales

Code Locale Comments
en English The source locale is identical to your code, which is written in English (neutral).
en_US English (United States) Override source to localize English for the United States.
en_GB English (Great Britain) Override source to localize English for Great Britain.
fr_FR French (France) Override source to translate and localize to French for France.

Handling the source locale and its variants

The en source locale is always 100% complete. New strings are always added here.

The en_US and en_GB locales will be almost identical. So rather than maintaining a unique localization for each string per locale, write the en source as neutral as possible. Then 95% of the strings in en_US and en_GB can be linked “Same As English” in Loco.

If the en source is updated, then all locale variants will automatically inherit that value. The remaining 5% of strings are translated per locale and override the source.

Handling additional languages and their variants

If there’s only one locale for a language, then don’t create a source locale.

The fr_FR locale is the only French localization, so an fr source is redundant. Adding it would just make create work in Loco. You can always consolidate to a source locale later.

Sometimes you do need additional source locales. For example, a German de source can support localizing de_DE + de_CH + de_AT. The de source would never be exported, but you could maintain three locale variants from one source efficiently.

Configuration

Account settings

Source Locale English

Always use a neutral locale for the source like English. Using a localized source like English (US) creates problems when managing multiple variants.

Project settings

Locale Settings
Source Locale English (neutral)
Locale Properties en (not en-US)
Locale Style legacy (for Magento)

Locale setup

Always set English (neutral) as the default locale. This is never exported — it’s simply a base. Locales for each Language (Country) should be created for exporting data.

Off Update asset name automatically
On Flag target translations as Fuzzy

Importing

Loco cannot import CSV files, which Magento uses. They must be converted to JSON first.

Convert CSV to JSON

  1. Copy/paste CSV data into this CSV to JSON conversion tool.
  2. Keep the defaults for steps 1–4.
  3. Step 5: set “CSV to JSON array” output.
  4. Copy/paste the result into your code editor.
  5. Manually fix the arrays so JSON matches this format:
{
    "Click <a href=\"%s\">here</a> to continue shopping.": "<a href=\"%s\">Continue Shopping</a>",
    "English": "English",
    "French": "Français",
    "Spanish": "Español"
}

Import

The project settings must specify the source locale as English (neutral) to match how strings appear in code. The CSV localizes from source to other locales like fr_FR.

Only import to non-English locales. English locales should be marked Same as English when translating. This cannot be done during import.

Adding assets manually

From the “manage” tab, click “new asset”.

Source text {type asset exactly as written in code}
ID {leave blank, generates automatically}
Type Plain text
Note: don’t use HTML even if the content contains HTML. This makes editing the code accurately more difficult because attributes are obscured.

Loco will strip all HTML on asset creation. After adding: immediately edit the asset, replace the HTML, and save again.

Translating

With “manage” tab

Use this tool only. This is the standard list of strings.

  • Use the locale selector to set the variant locale.
  • Use the status filter to show “Untranslated” strings only.

Translation flow:

  1. Expand an untranslated string.
  2. Change the view to split mode (vertical or horizontal). You must see and use the source locale override.
  3. Translate from the source locale (not the source code), or mark “Same as English”.
  4. Save.
  5. Collapse the string.

If the string is over 100 chars, the export will be broken. You must write a hash into your code and use this as the “asset name” in Loco with a source locale override to the desired full string.

<?php
// GravDept:
// Bypass asset name length in localise.biz.
// String: "The string that is really long and is over 100 chars which will break localise.biz when exporting from asset name."
echo $this->__('loco:hash:nice-contextual-label');
?>

With “translate” tab

Don’t use this tool. It makes translating fast, but it’s impossible to mark strings as “Same as English” from this tool. That entices you to assign translations which makes maintaining variant locales harder.

Exporting

There are multiple ways to export data, but only one works for Magento.

Spreadsheet > CSV Downloads

Don’t use these tools. The CSV index will be Loco’s generated asset ID (not the asset name). Magento requires the code to match the asset name in Loco.

Developer Tools > Language Pack Downloads

Export whole project

Don’t use the “Export Whole Project” tool. The assembled CSV will contain all locales. Magento requires separate CSV files for each locale.

Export current view

Use the “Export Current View” tool. Each locale must be exported individually.

Export Settings
Locale Single
Fallback English
Filter All tags
File format CSV
Index Name / description
Order Auto
Status Auto

The exported file is hobbiton-en_NZ.csv if the project short name and locale are hobbiton and en_NZ. It must be renamed for Magento’s structure:

/app/design/frontend/{package}/{theme}/locale/{locale}/translate.csv

More from the “Workspace” stack