Supported file formats

Weblate supports most translation format understood by translate-toolkit, however each format being slightly different, some issues with formats that are not well tested can arise.

Примечание

When choosing a file format for your application, it’s better to stick some well established format in the toolkit/platform you use. This way your translators can additionally use whatever tools they are used to, and will more likely contribute to your project.

Bilingual and monolingual formats

Both monolingual and bilingual formats are supported. Bilingual formats store two languages in single file—source and translation (typical examples are GNU gettext, XLIFF or Apple iOS strings). On the other side, monolingual formats identify the string by ID, and each language file contains only the mapping of those to any given language (typically Android string resources). Some file formats are used in both variants, see the detailed description below.

For correct use of monolingual files, Weblate requires access to a file containing complete list of strings to translate with their source—this file is called Monolingual base language file within Weblate, though the naming might vary in your paradigm.

Additionally this workflow can be extended by utilizing Intermediate language file to include strings provided by developers, but not to be used as is in the final strings.

Automatic detection

Weblate can automatically detect several widespread file formats, but this detection can harm your performance and will limit features specific to given file format (for example automatic addition of new translations).

Translation types capabilities

Capabilities of all supported formats:

Format Linguality [1] Plurals [2] Comments [3] Context [4] Location [5] Flags [8] Additional states [6]
GNU gettext bilingual yes yes yes yes yes [9] needs editing
Monolingual gettext mono yes yes yes yes yes [9] needs editing
XLIFF both yes yes yes yes yes [10] needs editing, approved
Java properties both no yes no no no  
Joomla translations mono no yes no yes no  
Qt Linguist .ts both yes yes no yes yes [10] needs editing
Android string resources mono yes yes [7] no no yes [10]  
Apple iOS strings bilingual no yes no no no  
PHP strings mono no yes no no no  
JSON files mono no no no no no  
JSON i18next files mono yes no no no no  
WebExtension JSON mono yes yes no no no  
.XML resource files mono no yes no no yes [10]  
CSV files mono no yes yes yes no needs editing
YAML files mono no yes no no no  
Ruby YAML files mono yes yes no no no  
DTD files mono no no no no no  
Flat XML mono no no no no yes [10]  
Windows RC files mono no yes no no no  
Excel Open XML mono no yes yes yes no needs editing
App store metadata files mono no no no no no  
Subtitle files mono no no no yes no  
[1]See Bilingual and monolingual formats
[2]Plurals are necessary to properly localize strings with variable count.
[3]Comments can be used to pass additional info about the string to translate.
[4]Context is used to differentiate identical strings used in different scopes (for example Sun can be used as an abbreviated name of the day «Sunday» or as the name of our closest star).
[5]Location of a string in source code might help proficient translators figure out how the string is used.
[6]Additional states supported by the file format in addition to «Not translated» and «Translated».
[7]XML comment placed before the <string> element, parsed as a developer comment.
[8]See Customizing behavior
[9](1, 2) The gettext type comments are used as flags.
[10](1, 2, 3, 4, 5) The flags are extracted from the non-standard attibute weblate-flags for all XML based formats. Additionally max-length:N is supported through the maxwidth attribute as defined in the XLIFF standard, see Specifying translation flags.

GNU gettext

Most widely used format for translating libre software. This was first format supported by Weblate and still has the best support.

Contextual info stored in the file is supported by adjusting its headers or linking to corresponding source files.

The bilingual gettext PO file typically looks like this:

#: weblate/media/js/bootstrap-datepicker.js:1421
msgid "Monday"
msgstr "Pondělí"

#: weblate/media/js/bootstrap-datepicker.js:1421
msgid "Tuesday"
msgstr "Úterý"

#: weblate/accounts/avatar.py:163
msgctxt "No known user"
msgid "None"
msgstr "Žádný"
Typical Weblate Component configuration
Filemask po/*.po
Monolingual base language file Empty
Template for new translations po/messages.pot
File format Gettext PO file

Monolingual gettext

Some projects decide to use gettext as monolingual formats—they code just the IDs in their source code and the string then needs to be translated to all languages, including English. This is supported, though you have to choose this file format explicitly when importing components into Weblate.

The monolingual gettext PO file typically looks like this:

#: weblate/media/js/bootstrap-datepicker.js:1421
msgid "day-monday"
msgstr "Pondělí"

#: weblate/media/js/bootstrap-datepicker.js:1421
msgid "day-tuesday"
msgstr "Úterý"

#: weblate/accounts/avatar.py:163
msgid "none-user"
msgstr "Žádný"

While the base language file will be:

#: weblate/media/js/bootstrap-datepicker.js:1421
msgid "day-monday"
msgstr "Monday"

#: weblate/media/js/bootstrap-datepicker.js:1421
msgid "day-tuesday"
msgstr "Tuesday"

#: weblate/accounts/avatar.py:163
msgid "none-user"
msgstr "None"
Typical Weblate Component configuration
Filemask po/*.po
Monolingual base language file po/en.po
Template for new translations po/messages.pot
File format Gettext PO file (monolingual)

XLIFF

XML-based format created to standardize translation files, but in the end it is one of many standards, in this area.

XML Localization Interchange File Format (XLIFF) is usually used as bilingual, but Weblate supports it as monolingual as well.

См.также

XML Localization Interchange File Format (XLIFF) specification

Translation states

Изменено в версии 3.3: Weblate ignored the state attribute prior to the 3.3 release.

The state attribute in the file is partially processed and mapped to the «Needs edit» state in Weblate (the following states are used to flag the string as needing edit if there is a target present: new, needs-translation, needs-adaptation, needs-l10n). Should the state attribute be missing, a string is considered translated as soon as a <target> element exists.

If the translation string has approved="yes", it will also be imported into Weblate as «Approved», anything else will be imported as «Waiting for review» (which matches the XLIFF specification).

While saving, Weblate doesn’t add those attributes unless necessary:

  • The state attribute is only added in case string is marked as needing edit.
  • The approved attribute is only added in case string has been reviewed.
  • In other cases the attributes are not added, but they are updated in case they are present.

That means that when using the XLIFF format, it is strongly recommended to turn on the Weblate review process, in order to see and change the approved state of strings.

See Dedicated reviewers.

Similarly upon importing such files (in the upload form), you should choose Import as translated under Processing of strings needing review.

Whitespace and newlines in XLIFF

Generally types or amounts of whitespace is not differentiated between in XML formats. If you want to keep it, you have to add the xml:space="preserve" flag to the string.

For example:

    <trans-unit id="10" approved="yes">
        <source xml:space="preserve">hello</source>
        <target xml:space="preserve">Hello, world!
</target>
    </trans-unit>

Specifying translation flags

You can specify additional translation flags (see Customizing behavior) by using the weblate-flags attribute. Weblate also understands maxwidth and font attributes from the XLIFF specification:

<trans-unit id="10" maxwidth="100" size-unit="pixel" font="ubuntu;22;bold">
   <source>Hello %s</source>
</trans-unit>
<trans-unit id="20" maxwidth="100" size-unit="char" weblate-flags="c-format">
   <source>Hello %s</source>
</trans-unit>

The font attribute is parsed for font family, size and weight, the above example shows all of that, though only font family is required. Any whitespace in the font family is converted to underscore, so Source Sans Pro becomes Source_Sans_Pro, please keep that in mind when naming the font group (see Managing fonts).

Typical Weblate Component configuration for bilingual XLIFF
Filemask localizations/*.xliff
Monolingual base language file Empty
Template for new translations localizations/en-US.xliff
File format XLIFF Translation File
Typical Weblate Component configuration for monolingual XLIFF
File mask localizations/*.xliff
Monolingual base language file localizations/en-US.xliff
Template for new translations localizations/en-US.xliff
File format XLIFF Translation File

Java properties

Native Java format for translations.

Java properties are usually used as monolingual translations.

Weblate supports ISO-8859-1, UTF-8 and UTF-16 variants of this format. All of them support storing all Unicode characters, it is just differently encoded. In the ISO-8859-1, the Unicode escape sequences are used (for example zkou\u0161ka), all others encode characters directly either in UTF-8 or UTF-16.

Примечание

Loading escape sequences works in UTF-8 mode as well, so please be careful choosing the correct enconding set to match your application needs.

Typical Weblate Component configuration
Filemask src/app/Bundle_*.properties
Monolingual base language file src/app/Bundle.properties
Template for new translations Empty
File format Java Properties (ISO-8859-1)

Joomla translations

Добавлено в версии 2.12.

Native Joomla format for translations.

Joomla translations are usually used as monolingual translations.

Typical Weblate Component configuration
Filemask language/*/com_foobar.ini
Monolingual base language file language/en-GB/com_foobar.ini
Template for new translations Empty
File format Joomla Language File

Qt Linguist .ts

Translation format used in Qt based applications.

Qt Linguist files are used as both bilingual and monolingual translations.

Typical Weblate Component configuration when using as bilingual
Filemask i18n/app.*.ts
Monolingual base language file Empty
Template for new translations i18n/app.de.ts
File format Qt Linguist Translation File
Typical Weblate Component configuration when using as monolingual
Filemask i18n/app.*.ts
Monolingual base language file i18n/app.en.ts
Template for new translations i18n/app.en.ts
File format Qt Linguist Translation File

Android string resources

Android specific file format for translating applications.

Android string resources are monolingual, the Monolingual base language file file is stored in a different location from the others res/values/strings.xml.

Typical Weblate Component configuration
Filemask res/values-*/strings.xml
Monolingual base language file res/values/strings.xml
Template for new translations Empty
File format Android String Resource

Примечание

Android string-array structures are not currently supported. To work around this, you can break your string arrays apart:

<string-array name="several_strings">
    <item>First string</item>
    <item>Second string</item>
</string-array>

become:

<string-array name="several_strings">
    <item>@string/several_strings_0</item>
    <item>@string/several_strings_1</item>
</string-array>
<string name="several_strings_0">First string</string>
<string name="several_strings_1">Second string</string>

The string-array that points to the string elements should be stored in a different file, and not be made available for translation.

This script may help pre-process your existing strings.xml files and translations: https://gist.github.com/paour/11291062

Apple iOS strings

Apple specific file format for translating applications, used for both iOS and iPhone/iPad application translations.

Apple iOS strings are usually used as bilingual translations.

Typical Weblate Component configuration
Filemask Resources/*.lproj/Localizable.strings
Monolingual base language file Resources/en.lproj/Localizable.strings
Template for new translations Empty
File format iOS Strings (UTF-8)

PHP strings

PHP translations are usually monolingual, so it is recommended to specify a base file with (what is most often the) English strings.

Example file:

<?php
$LANG['foo'] = 'bar';
$LANG['foo1'] = 'foo bar';
$LANG['foo2'] = 'foo bar baz';
$LANG['foo3'] = 'foo bar baz bag';
Typical Weblate Component configuration
Filemask lang/*/texts.php
Monolingual base language file lang/en/texts.php
Template for new translations lang/en/texts.php
File format PHP strings

Примечание

Translate-toolkit currently has some limitations in processing PHP files, so please double check that your files will not get corrupted before using Weblate in a production setup.

Following things are known to be broken:

  • Addition of new strings to a translation, every translation has to contain all strings (even if empty).
  • Handling of special characters like newlines.

См.также

PHP

JSON files

Добавлено в версии 2.0.

Изменено в версии 2.16: Since Weblate 2.16 and with translate-toolkit at-least 2.2.4, nested structure JSON files are supported as well.

JSON format is used mostly for translating applications implemented in JavaScript.

Weblate currently supports several variants of JSON translations:

JSON translations are usually monolingual, so it is recommended to specify a base file with (what is most often the) English strings.

Example file:

{
    "Hello, world!\n": "Ahoj světe!\n",
    "Orangutan has %d banana.\n": "",
    "Try Weblate at https://demo.weblate.org/!\n": "",
    "Thank you for using Weblate.": ""
}

Nested files are supported as well (see above for requirements), such a file can look like:

{
    "weblate": {
        "hello": "Ahoj světe!\n",
        "orangutan": "",
        "try": "",
        "thanks": ""
    }
}
Typical Weblate Component configuration
Filemask langs/translation-*.json
Monolingual base language file langs/translation-en.json
Template for new translations Empty
File format JSON nested structure file

JSON i18next files

Изменено в версии 2.17: Since Weblate 2.17 and with translate-toolkit at-least 2.2.5, i18next JSON files with plurals are supported as well.

i18next is an internationalization framework written in and for JavaScript. Weblate supports its localization files with features such as plurals.

i18next translations are monolingual, so it is recommended to specify a base file with (what is most often the) English strings.

Примечание

Weblate supports the i18next JSON v3 format. The v2 and v1 variants are mostly compatible, with exception of how plurals are handled.

Example file:

{
  "hello": "Hello",
  "apple": "I have an apple",
  "apple_plural": "I have {{count}} apples",
  "apple_negative": "I have no apples"
}
Typical Weblate Component configuration
Filemask langs/*.json
Monolingual base language file langs/en.json
Template for new translations Empty
File format i18next JSON file

WebExtension JSON

Добавлено в версии 2.16: This is supported since Weblate 2.16 and with translate-toolkit at-least 2.2.4.

File format used when translating extensions for Mozilla Firefox or Google Chromium.

Example file:

{
    "hello": {
        "message": "Ahoj světe!\n",
        "description": "Description",
        "placeholders": {
            "url" : {
              "content" : "$1",
              "example" : "https://developer.mozilla.org"
            }
        }
    },
    "orangutan": {
        "message": "",
        "description": "Description"
    },
    "try": {
        "message": "",
        "description": "Description"
    },
    "thanks": {
        "message": "",
        "description": "Description"
    }
}
Typical Weblate Component configuration
Filemask _locales/*/messages.json
Monolingual base language file _locales/en/messages.json
Template for new translations Empty
File format WebExtension JSON file

.XML resource files

Добавлено в версии 2.3.

A .XML resource (.resx) file employs a monolingual XML file format used in Microsoft .NET applications. It is [interchangeable with .resw, when using identical syntax to .resx](https://lingohub.com/developers/resource-files/resw-resx-localization).

Typical Weblate Component configuration
Filemask Resources/Language.*.resx
Monolingual base language file Resources/Language.resx
Template for new translations Empty
File format .XML resource file

CSV files

Добавлено в версии 2.4.

CSV files can contain a simple list of source and translation. Weblate supports the following files:

  • Files with header defining fields (source, translation, location, …). This is the recommended approach, as it is the least error prone.
  • Files with two fields—source and translation (in this order), choose Simple CSV file as file format
  • Files with fields as defined by translate-toolkit: location, source, target, ID, fuzzy, context, translator_comments, developer_comments

Предупреждение

The CSV format currently automatically detects the dialect of the CSV file. In some cases the automatic detection might fail and you will get mixed results. This is especially true for CSV files with newlines in the values. As a workaround it is recommended to omit quoting characters.

Example file:

Thank you for using Weblate.,Děkujeme za použití Weblate.
Typical Weblate Component configuration
Filemask locale/*.csv
Monolingual base language file Empty
Template for new translations locale/en.csv
File format CSV file

См.также

CSV

YAML files

Добавлено в версии 2.9.

The plain YAML files with string keys and values.

Example of a YAML file:

weblate:
  hello: ""
  orangutan": ""
  try": ""
  thanks": ""
Typical Weblate Component configuration
Filemask translations/messages.*.yml
Monolingual base language file translations/messages.en.yml
Template for new translations Empty
File format YAML file

См.также

YAML, Ruby YAML files

Ruby YAML files

Добавлено в версии 2.9.

Ruby i18n YAML files with language as root node.

Example Ruby i18n YAML file:

cs:
  weblate:
    hello: ""
    orangutan: ""
    try: ""
    thanks: ""
Typical Weblate Component configuration
Filemask translations/messages.*.yml
Monolingual base language file translations/messages.en.yml
Template for new translations Empty
File format Ruby YAML file

См.также

YAML, YAML files

DTD files

Добавлено в версии 2.18.

Example DTD file:

<!ENTITY hello "">
<!ENTITY orangutan "">
<!ENTITY try "">
<!ENTITY thanks "">
Typical Weblate Component configuration
Filemask locale/*.dtd
Monolingual base language file locale/en.dtd
Template for new translations Empty
File format DTD file

См.также

Mozilla DTD format

Flat XML files

Добавлено в версии 3.9.

Example of a flat XML file:

<?xml version='1.0' encoding='UTF-8'?>
<root>
  <str key="hello_world">Hello World!</str>
  <str key="resource_key">Translated value.</str>
</root>
Typical Weblate Component configuration
Filemask locale/*.xml
Monolingual base language file locale/en.xml
Template for new translations Empty
File format Flat XML file

См.также

Flat XML

Windows RC files

Добавлено в версии 3.0: Experimental support has been added in Weblate 3.0, and is not supported in Python 3.

Предупреждение

This format is still not supported on Python 3 due to bugs in underlying library, see <https://github.com/translate/translate/issues/3204>.

Example Windows RC file:

LANGUAGE LANG_CZECH, SUBLANG_DEFAULT

STRINGTABLE DISCARDABLE
BEGIN

IDS_MSG1 "Hello, world!\n"
IDS_MSG2 "Orangutan has %d banana.\n"
IDS_MSG3 "Try Weblate at http://demo.weblate.org/!\n"
IDS_MSG4 "Thank you for using Weblate."
END
Typical Weblate Component configuration
Filemask lang/*.rc
Monolingual base language file lang/en-US.rc
Template for new translations lang/en-US.rc
File format RC file

См.также

Windows RC files

App store metadata files

Добавлено в версии 3.5.

Metadata used for publishing apps in various app stores can be translated. Currently the following tools are compatible:

The metadata consists of several textfiles, which Weblate will present as separate strings to translate.

Typical Weblate Component configuration
Filemask fastlane/android/metadata/*
Monolingual base language file fastlane/android/metadata/en-US
Template for new translations fastlane/android/metadata/en-US
File format App store metadata files

Subtitle files

Добавлено в версии 3.7.

Weblate can translate various subtile files:

  • SubRip subtitle file (*.srt)
  • MicroDVD subtitle file (*.sub)
  • Advanced Substation Alpha subtitles file (*.ass)
  • Substation Alpha subtitle file (*.ssa)
Typical Weblate Component configuration
Filemask path/*.srt
Monolingual base language file path/en.srt
Template for new translations path/en.srt
File format SubRip subtitle file

См.также

Subtitles

Excel Open XML

Добавлено в версии 3.2.

Excel Open XML (.xlsx) files can be imported and exported.

When uploading XLSX files for translation, be aware that only the active worksheet is considered, and there must be at least a column called source (which contains the source string) and a column called target (which contains the translation). Additionally there should be the column called context (which contains the context path of the translation string). If you use the XLSX download for exporting the translations into an Excel workbook, you already get a file with the correct file format.

Others

Most formats supported by translate-toolkit which support serializing can be easily supported, but they did not (yet) receive any testing. In most cases some thin layer is needed in Weblate to hide differences in behavior of different translate-toolkit storages.

Adding new translations

Изменено в версии 2.18: In versions prior to 2.18 the behaviour of adding new translations was file format specific.

Weblate can automatically start new translation for all of the file formats.

Some formats expect to start with an empty file and only translated strings to be included (for example Android string resources), while others expect to have all keys present (for example GNU gettext). In some situations this really doesn’t depend on the format, but rather on the framework you use to handle the translation (for example with JSON files).

When you specify Template for new translations in Component configuration, Weblate will use this file to start new translations. Any exiting translations will be removed from the file when doing so.

When Template for new translations is empty and the file format supports it, an empty file is created where new strings will be added once they are translated.

The Language code style allows you to customize language code used in generated filenames:

Default based on the file format
Dependent on file format, for most of them POSIX is used.
POSIX style using underscore as a separator
Typically used by gettext and related tools, produces language codes like pt_BR.
BCP style using hyphen as a separator
Typically used on web platforms, produces language codes like pt-BR.
Android style
Only used in Android apps, produces language codes like pt-rBR.
Java style
User by Java—mostly BCP with legacy codes for Chinese.

Примечание

Weblate recognizes any of these when parsing translation files, the above settings only influences how new files are created.

Read only strings

Добавлено в версии 3.10.

Read-only strings from translation files will be included, but can not be edited in Weblate. This feature is natively supported by few formats (XLIFF and Android string resources), but can be emulated in others by adding a read-only flag, see Customizing behavior.