Documentation section

File Format - PHP

Learn how to use Localazy CLI for app and software localization with translations in PHP files.

Localazy allows using PHP files based on associative arrays such as those commonly used with Laravel framework. As an addition, we support for many different features - plurals, ICU, etc.

Plain PHP 🔗

Simple plain PHP files are supported out-of-the-box and no extra configuration is necessary.

<?php
return [
  "key1" => "Key 1",
  "key2" => "Key 2"
];
?>

It’s possible to use array() method instead of the short [] notation:

<?php
return array(
  "key1" => "Key 1",
  "key2" => "Key 2"
);
?>

Please note that we always output files with the short [] notation.

Structured PHP 🔗

Structured PHP files are supported by default and no configuration is necessary.

<?php
return [
  "parent" => [
    "child" => array(
       "another_nested_level" => "All is supported."
    )
  ]
];
?>

Multilingual PHP 🔗

Multilingual PHP files allow defining more languages inside a single file. Localazy supports multilingual PHP files with all the features describe in this document.

The top-level elements must be locale codes, and the corresponding source language as set in the project must be included.

The multilingual support must be enabled by adding multilingual to features in the upload section.

<?php
return [
  "en" => [
    "key" => "in English"
  ],
  "cs" => [
    "key" => "in Czech"
  ]
];

Locale codes can be defined using one of the supported methods:

  • LL_RR_Scrp
  • LL_Scrp_RR
  • LL_RR#Scrp
  • LL-RR-Scrp
  • LL-Scrp-RR
  • LL-RR#Scrp
  • LL+RR+Scrp
  • LL+Scrp+RR
  • Locale name (English, German, Czech, …)

Where LL is the language code (ISO 639-1), RR is the region code (ISO 3166-2), Scrp is the script code (ISO 15924). Parameters RR and Scrp can be omitted.

If the locale is not known to Localazy, it’s skipped during the processing of uploaded files.

You can define the output format by adding lang_format=xxx to features in the upload section where xxx is one of the following:

  • ll-rr#scrp
  • ll-rr-scrp
  • ll-scrp-rr
  • ll-scrp_rr
  • ll_rr_scrp
  • ll_scrp_rr
  • ll+rr+scrp
  • ll+scrp+rr
  • locale_name
  • bcp
  • android_noscript
  • android

It’s a good practice to define the output format since it may not be inherited from the input file.

Object-based PHP 🔗

By including content_as_object in features in the upload section, you can enable parsing of more complex PHP files where the content is based on sub-structures.

<?php
return [
  "key" => [
    "message" => "String content",
    "description" => "Optional additional comment for translators."
  ]
];
?>

Instead of message, you can use string, value, text, content or translation. Localazy remembers the field name and generates exactly the same document - just translated - for each of languages.

For the context information, instead of description, any of context, comment and developer_comment can be used.

All other features describe in this document are still available including structured PHP, arrays and plurals parsing, etc.

Arrays 🔗

Arrays are good but beware changing number of items to prevent mismatching translations. If your files contain incomplete arrays, don’t use array features at all.

Arrays defined by suffix 🔗

Localazy parses automatically also the suffixed variant shown below and present it to translators in a way that keeps items together and thus improves context and translation quality.

This feature can be enabled by adding array_br to features in the upload section.

<?php
return [
  "difficulty[0]" => "easy",
  "difficulty[4]" => "normal",
  "difficulty[7]" => "hard",
  "difficulty[9]" => "extreme"
];

The code above will be processed as an array and additional metadata will be stored, so Localazy can restore the indexes correctly.

All valid indexes are processed where valid index is non-negative integer value.

Plurals 🔗

Beware that plurals may lead to different output for translated files due to how plurals are handled in different languages.

<?php
return [
  // English has only two plural forms:
  "pluralOne" => "You have 1 item.",
  "pluralOther" => "You have %d items."

  // Czech has three plural forms:
  "pluralOne" => "Máte 1 položku.",
  "pluralFew" => "Máte %d položky.",
  "pluralOther" => "Máte %d položek."
];

Localazy knows the rules for different languages and adapt its interface to assist translators to correctly translate all mandatory forms.

Your app should be able to handle this. We are also working on SDK to help you with this task.

Allowed plurals types are: zero, one, two, few, many, other.

Defined by suffix 🔗

Several variants are available, and you can enable any of them and even combine them together. Localazy remembers how the plurals are formatted in the input file and keeps the same format for the translated files.

Add desired variants below to features in the upload section:

  • plural_postfix_sd for single dot variant.
  • plural_postfix_us for underscore variant.
  • plural_postfix_cc for camelCase variant.
  • plural_postfix_br for [brackets] variant.

Examples:

<?php
return [

  "single_dot" => [
    "users.one" => "There is one user.",
    "users.other" => "There are {{number}} users."
  ],

  "underscore" => [
    "users_one" => "There is one user.",
    "users_other" => "There are {{number}} users."
  ],

  "camelCase" => [
    "usersOne" => "There is one user.",
    "usersOther" => "There are {{number}} users."
  ],  

  "brackets" => [
    "users[one]" => "There is one user.",
    "users[other]" => "There are {{number}} users."
  ],
];

Defined as object 🔗

Enabled by plural_object in features in the upload section.

<?php
return [
  "users" => [
    "one" => "There is one user.",
    "other" => "There are $number users."
  ]
];

The object is considered plural if and only if all items are key-value strings with keys being valid plural types (zero, one, two, few, many, other).

If the condition above is not met, the object is not considered plural and is parsed as a structured PHP.

Defined using i18Next plural 🔗

Enabled by plural_i18next in features in the upload section.

Singular/plural variant:

<?php
return [
  "key" => "item",
  "key_plural" => "items"
];

All plural forms:

<?php
return [
  "key_0" => "zero",
  "key_1" => "singular",
  "key_2" => "two",
  "key_3" => "few",
  "key_4" => "many",
  "key_5" => "other"
];

Defined using ICU 🔗

Enabled by plural_icu in features in the upload section.

<?php
return [
  "users" => "There are {COUNT, plural, one {one user} other {# users}}."
];

Only one ICU plural can be used in the string as otherwise, it wouldn’t be possible to convert it to a specific Localazy plural structure. If more than two ICU plurals are contained, the string is kept in the original form.

Allowed plurals types are: zero (=0), one (=1), two (=2), few, many, other.

Other ICU types like gender, number, etc. can be used but will not be converted and will be kept in string in the original form.

Skipping empty translations 🔗

By default, empty translations are imported as empty strings. If your format use empty translations for untranslated texts, add skip_empty to features in the upload section.

Filtering untranslated strings 🔗

By default, when the output file is generated, Localazy uses texts from the source languages when the translation in the exported language is missing.

This approach is safeguarding you from missing keys that can lead to crashes in some solutions/frameworks.

This feature can be disable by adding filter_untranslated to features in the upload section and reuploading your source language file.

Using key as the source translation 🔗

There is a special format where the key is also the source language translation. It’s possible to enable the support for this format by adding source_is_key in features in the upload section.

<?php
return [
  "Text in the source language" => "Translation in the defined language"
];

String concatenation / variables 🔗

It’s possible to use string interpolation with variables.

This is supported:

<?php
return [
  "key" => "String with variable: $variable"
];

It’s possible to use string concatenation, but only without variables.

This is supported:

<?php
return [
  "key" => "multiline" .
           "strings" .
           "can" .
           "be" .
           "concatenated"
];

Variables in concatenation are not supported.

This is NOT supported:

<?php
return [
  "key" => "There is " . VARIABLE . " items."
];

Please use string interpolation or placeholders instead.

Features overview 🔗

The table below is a summary of all available features for PHP parser.

Feature Description
content_as_object Enable object-based PHP.
multilingual Enable support of multilingual PHP files.
lang_format=xxx Define how to output locales for multilingual files.
array_br Parse strings with keys suffixed by [x] as arrays.
plural_postfix_us Parse strings with keys suffixed by _type as plural.
plural_postfix_cc Parse strings with keys suffixed by Type as plural.
plural_postfix_br Parse strings with keys suffixed by [type] as plural.
plural_postfix_sd Parse strings with keys suffixed by .type as plural.
plural_object Enable plurals defined as objects.
plural_i18next Enable i18Next plurals.
plural_icu Enable support for ICU plurals.
skip_empty Consider empty translations as untranslated.
filter_untranslated Don’t use the source language texts for missing translations.
source_is_key Use the key as the source translation.