XWiki Translations Formats

Last modified by Simon Urli on 2020/06/25 09:08

XWiki Standard is using 3 different translations file formats in order to allow content and message localization.
This page aims at formalizing those file formats to help developing tools for XWiki localization.

XWiki Java Properties

Description

This file format allows to define translation messages to be used in Java or script code.

It's basically using a ResourceBundle with .properties files that follows the same naming conventions. That kind of file format is standard in Java (see dedicated Java tutorial to use Resource Bundle with properties), however XWiki internally use MessageFormat to allow using arguments in the translation messages that implies some specific handling of simple quote. Moreover, contrary to some other localization practices, missing translations are always output as comment in translation files, with a dedicated prefix. Finally, deprecated translations are also handled with this format with some custom comments.

File format

The format is a standard Java key-values property file.
By convention the only used delimiter is =. And the comments are using #.

Encoding

The files are encoded using ISO-8859-1.

File names

The files are always placed in src/main/resources in a Maven module.
The source file name must be: ApplicationResources.properties.
All translations files are named ApplicationResources_LOCALE.properties, where LOCALE is a Java supported Locale name. Examples: ApplicationResources_fr.properties  or ApplicationResources_pt_BR.properties

The full list of Java supported Locale is available there: https://www.oracle.com/java/technologies/javase/jdk8-jre8-suported-locales.html

Escaping simple quotes

XWiki is internally using MessageFormat to handle translations.
This means that numbered arguments are authorized in translations (e.g. "A message for {0}"), however simple quotes (') must be escaped by doubling them only when a numbered argument is used.

For example, to translate "This is a message 'a'", the source localization will be: 

key=This is message 'a'

Now, to translate "This is message 'a' for {0}", the source localization will be:

key=This is message ''a'' for {0}

Output of missing translations

In a translation file, missing translations are systematically output by printing a comment with the source translation, containing the prefix Missing: .
For example, in a dedicated module, we can have the source localization file ApplicationResources.properties containing:

key1=Translation 1
key2=Translation 2
key3=Translation 3

and the file ApplicationResources_fr.properties containing the following partial translation:

key1=Traduction 1
### Missing: key2=Translation 2
key3=Traduction 3

Deprecated translations

Deprecated translations are handled with this format, by moving the key-values in a dedicated section created with specific custom comments: 

## Used to indicate where deprecated keys start
#@deprecatedstart

## until 7.3M1
activity.link.title=Located in {0} » {1} » {2}

## Used to indicate where deprecated keys end
#@deprecatedend

Real examples

XWiki Page Properties

Description

This file formats allows to define translations messages to be used in Java or script code, but also allows to edit translations directly in XWiki.

XWiki Page Properties translations are using the same concepts as the XWiki Java Properties except that the translations are not placed in .properties file, but inside the content of an XWiki document that contains a specific XWiki object. Moreover the encoding is different than for XWiki Java Properties files.

File Format

Those translations are kept in a XML file following the XWiki Document File specification.
Moreover they need to respect the following rules:

  • source translation files need to contain a XWiki.TranslationDocumentClass xobject as documented in Localization Extension
  • translation files needs to have the translation tag set to 1 and the language tag specifying the locale of the translation. Example:
      <language>fr</language>
     <defaultLanguage>en</defaultLanguage>
     <translation>1</translation>

The actual key-value properties are always stored under the content tag of the file, both for source and translation files, and they must obey the same rules as XWiki Java Properties regarding escaping and missing translations.

Encoding

Encoding of those files is UTF-8.

File names

Those files are systematically stored in a XAR module under directory src/main/resources.
By conventions, the end of source translations file should be Translations.xml. Now the full name depends on what is translation exactly, the same module might have several translations source files, for example:

  • AdminTranslations.xml
  • TemplateTranslations.xml

Now translations files must use the same name as their source file, but with the suffix corresponding to their locale: sourcenameTranslations.LOCALE.xml, for example:

  • AdminTranslations.fr.xml
  • TemplateTranslations.pt_BR.xml

Real examples

XWiki Full Content Translation

Description

This file format allows to translate a whole page content: it cannot be used to translate specific messages.

This translation file format is mainly used directly inside XWiki when users are performing whole document translations. Its usage in development should remain limited to specific cases, such as XWiki homepage, integrated full-pages documentation (Sandbox), etc. The reason for limiting its usage, is that those files generally contain XWiki syntax which has to be preserved in the translations, and it's difficult to guarantee that.

File format

Those translations are kept in a XML file following the XWiki Document File specification.
Contrary to XWiki Page Properties, the source files don't have any special XWiki objects, they are plain standard XWiki documents.
Translations files, still needs to respect the same rules as XWiki Page Properties:

  • they need to have the translation tag set to 1 and the language tag specifying the locale of the translation. Example:
      <language>fr</language>
     <defaultLanguage>en</defaultLanguage>
     <translation>1</translation>

Here the content of the page can be any XWiki content and doesn't have to follow any convention.

Encoding

Those files are encoded in UTF-8.

File names

As for XWiki Page Properties the files are systematically stored in a XAR module under directory src/main/resources.

But contrary to XWiki Page Properties, the source files don't have any naming convention to respect: it can be any XWiki page name.
Translations files, still have to respect the same convention as for XWiki Page Properties, they are using their source file name, with the locale prefix: sourcename.LOCALE.xml, for example:

  • WebHome.fr.xml
  • WebHome.pt_BR.xml

Real examples

Tags:
   

Get Connected