Show last authors
1 {{box cssClass="floatinginfobox" title="Content"}}
2 {{toc/}}
3 {{/box}}
4
5
6 XWiki Standard is using 3 different translations file formats in order to allow content and message localization.
7 This page aims at formalizing those file formats to help developing tools for XWiki localization.
8
9 = XWiki Java Properties =
10
11 == Description ==
12
13 This file format allows to define translation messages to be used in Java or script code.
14
15 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>>https://docs.oracle.com/javase/tutorial/i18n/resbundle/propfile.html]]), 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.
16
17 == File format ==
18
19 The format is a [[standard Java key-values property>>https://docs.oracle.com/javase/8/docs/api/java/util/Properties.html]] file.
20 By convention the only used delimiter is ##=##. And the comments are using #####.
21
22 == Encoding ==
23
24 The files are encoded using ##ISO-8859-1##.
25
26 == File names ==
27
28 The files are always placed in ##src/main/resources## in a Maven module.
29 The source file name must be: ##ApplicationResources.properties##.
30 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##.
31
32 The full list of Java supported Locale is available there: https://www.oracle.com/java/technologies/javase/jdk8-jre8-suported-locales.html
33
34 == Escaping simple quotes ==
35
36 XWiki is internally using [[MessageFormat>>https://docs.oracle.com/javase/8/docs/api/java/text/MessageFormat.html]] to handle translations.
37 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**.
38
39 For example, to translate "This is a message 'a'", the source localization will be:
40
41 {{code language="none"}}
42 key=This is message 'a'
43 {{/code}}
44
45 Now, to translate "This is message 'a' for {0}", the source localization will be:
46
47 {{code language="none"}}
48 key=This is message ''a'' for {0}
49 {{/code}}
50
51 == Output of missing translations ==
52
53 In a translation file, missing translations are systematically output by printing a comment with the source translation, containing the prefix //Missing: //.
54 For example, in a dedicated module, we can have the source localization file ##ApplicationResources.properties## containing:
55
56 {{code language="none"}}
57 key1=Translation 1
58 key2=Translation 2
59 key3=Translation 3
60 {{/code}}
61
62 and the file ##ApplicationResources_fr.properties## containing the following partial translation:
63
64 {{code language="none"}}
65 key1=Traduction 1
66 ### Missing: key2=Translation 2
67 key3=Traduction 3
68 {{/code}}
69
70 == Deprecated translations ==
71
72 Deprecated translations are handled with this format, by moving the key-values in a dedicated section created with specific custom comments:
73
74 {{code language="none"}}
75 ## Used to indicate where deprecated keys start
76 #@deprecatedstart
77
78 ## until 7.3M1
79 activity.link.title=Located in {0} » {1} » {2}
80
81 ## Used to indicate where deprecated keys end
82 #@deprecatedend
83 {{/code}}
84
85 == Real examples ==
86
87 * [[XWiki Commons Job API Source>>https://github.com/xwiki/xwiki-commons/blob/master/xwiki-commons-core/xwiki-commons-job/xwiki-commons-job-api/src/main/resources/ApplicationResources.properties]]
88 * [[XWiki Commons Job API French translation>>https://github.com/xwiki/xwiki-commons/blob/master/xwiki-commons-core/xwiki-commons-job/xwiki-commons-job-api/src/main/resources/ApplicationResources_fr.properties]]
89
90 = XWiki Page Properties =
91
92 == Description ==
93
94 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.
95
96 XWiki Page Properties translations are using the same concepts as the [[XWiki Java Properties>>||anchor="HXWikiJavaProperties"]] 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.
97
98 == File Format ==
99
100 Those translations are kept in a XML file following the [[XWiki Document File specification>>extensions:Extension.XAR Module Specifications||anchor="HDocumentXMLfile"]].
101 Moreover they need to respect the following rules:
102 * source translation files need to contain a ##XWiki.TranslationDocumentClass## xobject as documented in [[Localization Extension>>extensions:Extension.Localization||anchor=""HRegisterawikitranslation"]]
103 * translation files needs to have the ##translation## tag set to ##1## and the ##language## tag specifying the locale of the translation. Example:(((
104
105 {{code language="xml"}}
106 <language>fr</language>
107 <defaultLanguage>en</defaultLanguage>
108 <translation>1</translation>
109 {{/code}}
110
111 )))
112
113 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>>||anchor="HXWikiJavaProperties"]] regarding escaping and missing translations.
114
115 == Encoding ==
116
117 Encoding of those files is UTF-8.
118
119 == File names ==
120
121 Those files are systematically stored in a [[XAR module>>extensions:Extension.XAR Module Specifications]] under directory ##src/main/resources##.
122 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:
123 * AdminTranslations.xml
124 * TemplateTranslations.xml
125
126 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:
127 * AdminTranslations.fr.xml
128 * TemplateTranslations.pt_BR.xml
129
130 == Real examples ==
131
132 * [[XWiki Platform Administration Source>>https://github.com/xwiki/xwiki-platform/blob/master/xwiki-platform-core/xwiki-platform-administration/xwiki-platform-administration-ui/src/main/resources/XWiki/AdminTranslations.xml]]
133 * [[XWiki Platform Administration French Translation>>https://github.com/xwiki/xwiki-platform/blob/master/xwiki-platform-core/xwiki-platform-administration/xwiki-platform-administration-ui/src/main/resources/XWiki/AdminTranslations.fr.xml]]
134
135 = XWiki Full Content Translation =
136
137 == Description ==
138
139 This file format allows to translate a whole page content: it cannot be used to translate specific messages.
140
141 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.
142
143 == File format ==
144
145 Those translations are kept in a XML file following the [[XWiki Document File specification>>extensions:Extension.XAR Module Specifications||anchor="HDocumentXMLfile"]].
146 Contrary to [[XWiki Page Properties>>||anchor="HXWikiPageProperties"]], the source files don't have any special XWiki objects, they are plain standard XWiki documents.
147 Translations files, still needs to respect the same rules as XWiki Page Properties:
148 * they need to have the ##translation## tag set to ##1## and the ##language## tag specifying the locale of the translation. Example:(((
149
150 {{code language="xml"}}
151 <language>fr</language>
152 <defaultLanguage>en</defaultLanguage>
153 <translation>1</translation>
154 {{/code}}
155
156 )))
157
158 Here the content of the page can be any XWiki content and doesn't have to follow any convention.
159
160 == Encoding ==
161
162 Those files are encoded in UTF-8.
163
164 == File names ==
165
166 As for [[XWiki Page Properties>>||anchor="HXWikiPageProperties"]] the files are systematically stored in a [[XAR module>>extensions:Extension.XAR Module Specifications]] under directory ##src/main/resources##.
167
168 But contrary to XWiki Page Properties, the source files don't have any naming convention to respect: it can be any XWiki page name.
169 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:
170 * WebHome.fr.xml
171 * WebHome.pt_BR.xml
172
173 == Real examples ==
174
175 * [[XWiki Platform Sandbox Source Homepage>>https://github.com/xwiki/xwiki-platform/blob/master/xwiki-platform-core/xwiki-platform-sandbox/src/main/resources/Sandbox/WebHome.xml]]
176 * [[XWiki Platform Sandbox French translation Homepage>>https://github.com/xwiki/xwiki-platform/blob/master/xwiki-platform-core/xwiki-platform-sandbox/src/main/resources/Sandbox/WebHome.fr.xml]]

Get Connected