Main menu

Working with locales across platforms

Loco expresses locales with standard codes, or language tags as you might know them. This page explains how developers interact with these codes when using the API. General information about managing custom project locales is available here.

In many cases it won't matter if your own codes don't exactly match the ones in Loco. However, if you're doing any of the following things it's recommended that they do:

  • working with the Loco locales API.
  • exporting files that contain language tags.
  • exporting Zip archives containing multiple locales.

Standard language tags

To open with an example, here are the two most common ways "Greek" might be represented in your Loco project:

  • "el" (language code only)
  • "el-GR" (region code indicates the country of Greece)

In accordance with RFC 5646, the following variations are also supported by Loco:

  • "grc" (three character language code for Ancient Greek)
  • "el-Latn" (script code indicates transliteration to the Latin alphabet)
  • "el-polyton" (variant code indicates Polytonic Greek)
  • "el-x-custom" (private use extension for whatever else you need)

All Loco project locales follow this syntax, but if your platform uses something different we have ways to ensure compatibility.

Custom language tags

If you need to use different codes from those Loco provides, you can specify a custom language tag for each of your project locales.

This is useful in a number of cases:

  • to use an underscore instead of a hyphen, such as "el_GR";
  • to use an unsupported syntax, such as "zh-yue" for Cantonese;
  • to use codes from another standard, such as "iw" for Hebrew, or "ger" for German;
  • to use completely non-standard references, like "english".

Once a custom language tag is defined it will be used across your project whenever Loco would normally use the standard form. This doesn't affect the functionality of Loco at all. A custom tag is just a label for your own purposes.

Platform aliases

The custom language tag is effectively an alias for the tag that Loco would normally use. In addition to this alias, Loco lets you define multiple aliases for targeting different platforms. For example: You could export Simplified Chinese as "zh-Hans" for iOS, but "zh-rCN" for Android.


Platform aliases are used by the Export API in two situations:

  1. When file paths are generated for Zip archives;
  2. When the file itself contains language tag references.

Language tags in file paths

For generating Zip archives, Loco defines a default path for each exportable file format. For example:

  • el-GR.lproj/Localizable.strings (for iOS);
  • res/values-el-rGR/strings.xml (for Android).

The language tag that appears in these paths can be customized by setting a platform alias. The following aliases are available for their respective export formats:

"android", "chrome", "codeigniter", "gettext", "ios", "java", "qt", "rails", "symfony".

The Export API also provides a custom file path parameter. This means you don't have to stick to the formats above, you can define any named alias you like and pass it to the Zip exporter. See documentation on custom file paths.

Language tags in file contents

Not all file formats contain language tag references. For those that do, the following aliases affect how they will be written to the relevant export:

  • "gettext" (defines the contents of the Language header in PO files)
  • "symfony" (defines the language attributes exported into Symfony XLIFF files)
  • "rails" (defines the hash keys used in Ruby on Rails YAML files)
  • "ios" (defines the language attributes exported into Xcode XLIFF files)
  • "icu" (defines the table key used in ICU resource bundle source files)
  • "ng" (defines the hash keys used in Angular JavaScript files)
  • "qt" (defines the language attributes exported into Qt Framework TS files)

Note that Loco does not validate your custom language tags against the file format's syntax. For example: always use a valid xml:lang attribute when exporting XML files.

Built-in platform formatting

Loco performs some platform-specific formatting automatically unless you override it with your own platform alias. This is limited to platforms that tend to use underscores instead of hyphens, plus "android" (which places the letter "r" before the region). All other platforms use the standard form by default.

For example, if you have locale "el-GR" and export to Android, the language tag "el-rGR" will be used unless you've overridden this with an alias called "android". Similarly this would be exported as "el_GR" into PO files unless you specified your own "gettext" alias.

Note that this formatting is also applied if you've specified a custom language tag but not a platform alias. For example, if you have locale "zh-Hans" but set your custom tag to "zh_CN" your Android export will use "zh-rCN". This is your custom tag, but in the Android format.

If your custom tag is a non-standard format, it will just be used as it is. For example the tag "english" would not be parsed as a language tag so it would be exported without any formatting.

Notes on BCP47 and RFC 5646

If you're familiar with these standards, please note a few of Loco's storage limitations:

  • Only one variant subtag up to 8 characters is supported per locale.
  • Only one extension OR private use subtag up to 12 characters is supported per locale.
  • All project locales must have a language. If no language applies, you can specify "zxx" instead.
  • Loco only uses one code per language (e.g. Greek is "el", and not "gre" or "ell").
  • Loco doesn't recognize extended language or grandfathered subtags.

These restrictions only affect how Loco stores locales internally. You can always specify an alias if you need to use unsupported codes.

Legacy projects

When Loco first launched it only supported the "xx_YY" style of locale codes. This legacy style became optional on November 8th 2015. If your project is old you can upgrade it to use standard language tags in your project settings.