Main menu

Export paths

Custom export path templates

For generating Zip archives, Loco defines a default path for each exportable file format. For example, an iOS project might be exported with paths like this:

en.lproj/Localizable.strings
fr.lproj/Localizable.strings

You can customize the format of these paths by passing the path parameter to the Export API's archive endpoint. This parameter takes the form of a string template. For the examples above the following template would work:

{locale}.lproj/Localizable.strings

The endpoint takes this parameter in the query string, so make sure it's properly escaped. Here's the full URL:

https://localise.biz/api/export/archive/strings.zip?path=%7Blocale%7D.lproj%2FLocalizable.strings

Platform aliases

The {locale} placeholder will be expanded into the default language tag for each project locale. If you've set a custom language tag it will be used, but you can specify any named alias with the following syntax:

{locale|alias:ios}.lproj/Localizable.strings

Note the use of the pipe ("|") to specify the "alias" filter, then the colon (":") to provide the argument "ios". This is the name of the alias to use, and you can call it whatever you like. See platform aliases.

Template syntax

The following placeholders can be used in export path templates:

  • {locale}
    This expands to the full locale code and can be filtered as described above to render for specific platforms.

  • {lang}
    This expands to just the language subtag of the locale, e.g. {lang}.xml would expand to "en.xml" for the locale "en-GB".

  • {script}, {region}, {variant} and {extension}
    As with the language token, these expand just to the given subtag. e.g. {lang}_{region}.po would expand to "en_GB.po" for the locale "en-GB-x-ignore".

  • {iso_639_2} and {iso_639_3}
    These expand to the ISO language code in the given standard. e.g. {iso_639_2}-{region}.xml would expand to "ger-DE.xml" for the locale "de-DE".

  • {ext}
    This expands to the default file extension of the current format. e.g. Localizable.{ext} would expand to "Localizable.strings" when exporting to iOS strings.

  • {namespace}
    This expands to the project slug or the namespace query string parameter if passed. e.g. for exporting to WordPress you might use: lang/{namespace}-{locale|alias:gettext}.po

Note: Any similarity to a known syntax (like ICU MessageFormat) is coincidental. Invalid formatting will generally be ignored.

Skipping empty values

You may notice that a template like {lang}_{region} poses a problem if there is no region. The solution is to put the separator between the opening brace and the placeholder, like so:

locales/{lang}{_region}.po

This will suppress the "_" character if the region placeholder evaluates to an empty string.

Note: This conditional separator can be any non alphabetical character (except "%"). This means whitespace preceding the placeholder name is treated literally.

Filters

The template syntax supports filters separated by a pipe ("|"). The following filters are also supported:

  • alias
    As documented above: This applies to the {locale} placeholder only.

  • upper and lower
    These do what you probably expect. e.g. {lang|upper}-{region|lower} would expand to "EN-gb" for the locale "en-GB".

  • unless
    This filter suppresses a token if the expanded value is not the given argument. e.g. values{-locale|unless:en} would expand to "values-de" for German, but simply "values" for English. Note that the value passed to the filter will be compared exactly with the expanded token.

  • if_source and if_target
    These filters yield the token according to whether the current locale is (or isn't) the project default. e.g. values{-lang|if_target} would expand to "values-de" for German, but simply "values" for English, assuming that English is the configured source locale.

Tip: You can chain filters together as long as the order makes sense. For example: values{-locale|if_target|alias:android}.xml.

Legacy syntax

Loco originally used a syntax like {%locale} with a percent symbol. This is no longer required, but will continue to be supported. The "%" symbol is simply ignored, which means you can't use it as conditional separator.