About the Loco file exporters

There are two ways to export translations from your Loco project:

• From your dashboard.
• Via the Export API

Dashboard

The "Export translations" window in your project dashboard provides several GUIs for exporting files. You can open this from anywhere you see the :download icon:.

The dashboard export interfaces are just front ends to the API, which is outlined below.

Export API

Exporting language packs via the REST API provides the most control and is the best way to integrate Loco into your development workflow.

See the full endpoint documentation

Supported export formats

See the list of supported export formats in the API documentation.

The list of supported file formats is constantly growing, but if you don't see yours, please tell us.

Export options

The dashboard and the API support some common options for exporting your translations. Here's an explanation of them all:

Locales

You can export a single locale, or your whole project depending on what your target platform requires. It's also possible to export no locales if you need a template containing just keys and no translations.

Some file formats support multiple locales in a single file. For those that don't, Loco offers a convenient Zip archive for exporting multiple single-language files.

Filter by tag

If you've tagged the assets in your project, the filter parameter will let you export groups of them separately into their own files. Because tags operate across locales, this filter will export the same subset of assets to all your target language files.

• Specifying multiple tags will match any asset tagged by any of them.
• Via the API you can match any tag with * and negate tags by prefixing with !. See the URI parameters.

Status and flags

The status parameter exports assets based on their completed state or flag. For example, you can export only "Translated" assets in a given locale, or the opposite ("Untranslated"), or every translation in need of review ("Fuzzy").

• Via the API you can negate a status or flag by prefixing with !. See the URI parameters.
• Bear in mind that translation status may differ between locales. Exporting multi-language files by a single status can produce confusing results.

Alternative indexing

The index parameter allows you to specify an alternative lookup key for your target file. If you leave this empty (or select "Auto" in the dashboard) Loco will use the right key for the current format. For example, a PO file will be indexed by "text" but Android XML resources will be indexed by "id".

• Generic formats such as JSON tend to use the ID by default, but you can switch to "text" if your application uses source language keys.
• You can select a specific locale for use as the index. This implies "text" but overrides your default project locale.

Fallback locales

Specifying the fallback parameter will use an alternative locale for any missing translations. Multiple language tags can be separated by commas, and will be tried in order until a translation exists.

Note that a missing translation is not the same as a deliberately blank, or flagged translation. Only truly "untranslated" items will invoke the fallback logic.

You can specify auto instead of a language tag. This applies a simple truncation algorithm to the export language, and then appends the project source locale. For example, exporting de-AT.json with fallback=auto is the same as specifying fallback=de,en (assuming your source language is English). This behaviour can be overridden by a custom value in your locale settings (developer tab). See this announcement for an example.

Sort order

The default order of exported translations is the order in which the assets were added to your project, (first in, first out), but the order parameter allows you to change this.

Omitting the value is equivalent to specifying "created", but "id" is also supported. This will sort translations alphabetically by their Asset ID. This is useful when reviewing file exports manually.

Additional API options

These advanced options are only available via the Export API:

String formatting

The printf parameter allows string formatting to be converted between the various formats that Loco supports. For full details on this topic, see Working with formatting syntax.

Some formats are converted automatically, (e.g. exporting Java strings to iOS will convert for Objective C) but any conversion can be specified. For example /api/export/template.pot?printf=php.

Character encodings

The charset parameter controls the text encoding of the exported file. Most file formats default to UTF-8 with the exceptions of iOS .strings files (which default to UTF-16BE for historical reasons) and Java .properties files which default to latin1. Append charset=utf8 to either of these formats to prevent the default encoding.

You can also send the Accept-Charset header with a range of options such as latin1;q=0.8,utf8. The header is silently ignored if no supported encodings are found, whereas specifying an invalid charset parameter will produce a 406 error.

Note that this option also affects binary file formats. Despite having no text encoding, any strings embedded into binary data will be encoded as requested. For example, Gettext MO files will be compiled with the given encoding and have their Content-Type header set accordingly.

Line breaks

The breaks parameter allows you to force platform-specific line endings such as Unix and DOS. Loco uses Unix (LF) line endings by default, but if you're working with another platform try enforcing your preferred style: For example breaks=dos.

As with character encodings, this option also affects strings embedded in binary files.

Strip comments

The no-comments parameter disables redundant comments in file formats that support them. It also suppresses the README.txt file added to Zip archives.

This option doesn't suppress metadata when it's a meaningful part of the language pack schema, or when it's required for functionality.

Disable key expansion

The no-expand parameter disables key expansion of IDs containing dot characters. This only applies to file formats that supported nested structures, and the indexing mode is ID.

A common example is JSON, where the "foo.bar" would expand to produce an object like {"foo":{"bar":""}. If this behaviour is undesirable, specify e.g. /api/export/locale/en.json?no-expand. See Key collisions for more detail on this topic.

This option was previously called no-folding. For backward compatibility this will continue to work, but the name was confusing.

Key collision handling

The collisions parameter specifies the strategy for resolving non-unique keys. (See key collisions for detailed examples). You don't need this option if your export is indexed by unique, flat IDs. It primarily affects the behaviour of text-indexed files, or nested object formats.

The default behaviour depends on the specific file format, but it's recommended to resolve conflicts rather than to rely on automatic handling. Specifying collisions=fail enables a strict mode that makes it easy to identify collisions.

Note that the behaviour of collision merging changed in October 2024. The announcement includes some useful examples.

Missing strings?

If your export is missing some translations, here are some things to check:

• Are the missing items filtered out?
  If you're filtering by tag, check the assets are tagged correctly. Note that plural forms are treated as separate assets in Loco, so check all forms are tagged for export, not just the singular form.

• Do the missing items have a translation in your default language?
  Some file formats deliberately exclude translations that have no source text. This is to avoid duplicate empty keys. You can override this by appending status=all to the export URL, or possibly you need to specify index=id to ensure a unique lookup key.