Hide last authors
Thomas Mortagne 7.1 1 {{box cssClass="floatinginfobox" title="**Contents**"}}
2 {{toc/}}
3 {{/box}}
Vincent Massol 1.1 4
Vincent Massol 9.1 5 = Tutorials =
6
Vincent Massol 16.1 7 * [[Tutorial for Internationalizing a Form>>Documentation.DevGuide.Tutorials.TranslationsTutorial.WebHome]]
Vincent Massol 9.1 8
Silvia Macovei 6.2 9 = Using properties located in XWiki pages =
Vincent Massol 1.1 10
Manuel Smeria 11.3 11 * Create a page that will host your key/value pairs
Thomas Mortagne 7.1 12 * Enter all the key/value pairs in that page ({{warning}}use the wiki editor{{/warning}}). For example:(((
Vincent Massol 6.3 13 {{code language="none"}}
Vincent Massol 1.2 14 greeting=hello
15 welcome=Welcome
Vincent Massol 1.12 16 withparams=I can {0} pass {1} {2} params too using the Java MessageFormat syntax
Silvia Macovei 6.1 17 {{/code}}
slauriere 18.1 18
19 NB: the Java MessageFormat syntax is described in the [[MessageFormat Javadoc>>https://docs.oracle.com/javase/7/docs/api/java/text/MessageFormat.html]]. There's in particular an important peculiarity for messages with parameters: single quotes need to be doubled to show up in the translated string, which is not the case for messages that are not parameterized.
Vincent Massol 6.3 20 )))
Raphaël Jakse 20.3 21 * While editing this page in wiki mode, you will be able to translate it in other languages by clicking on languages next to "Translate this page in" in the "Page Translations" sections of the right panel.(((
Silvia Macovei 6.1 22 {{info}}
23 To enable multiple languages you'll need to go to the Administration page and set MultiLingual to true and list the different languages you wish to use in the Languages field.
24 {{/info}}
Vincent Massol 6.4 25 )))
Vincent Massol 12.1 26 * Tell XWiki that your page is a Translation page by adding an Object of type ##TranslationDocumentClass## to your page.
Vincent Massol 15.1 27 * On the page where you want to use use either the ##~{~{translation}}## macro or the Localization Script Service (check the document for the [[Localization module>>extensions:Extension.Localization Module]]). Quick examples:(((
Vincent Massol 12.1 28 From wiki syntax:
29
Silvia Macovei 6.1 30 {{code}}
Vincent Massol 12.1 31 {{translation key="key"/}}
32 {{/code}}
33
34 From Script (Velocity in this example):
35
36 {{code}}
Clemens Robbenhaar 11.5 37 $services.localization.render("key")
38 $services.localization.render("key", ["param1", "param2", ...])
Silvia Macovei 6.1 39 {{/code}}
Vincent Massol 1.2 40
slauriere 17.1 41 where ##key## is the key for the message to retrieve. Parameters can also be passed as is shown in the second syntax above. Beware the parameters need to be passed as an array, not a plain String even if there's only one parameter: {{code}}$services.localization.render("key", ["param1"]){{/code}}.
Vincent Massol 6.3 42 )))
Vincent Massol 1.16 43
Vincent Massol 12.1 44 == Old way ==
45
46 Prior to XWiki 4.3, the way to register a Document Resource Bundle was by going to the Administration page, selecting the "Localization" section and entering it in the "Internationalization Document Bundles" field. You could specify several pages, separated by commas.
47
48 {{info}}
49 When creating "Internationalization Document Bundles", you should avoid naming the pages with names that include spaces. For example, a document name of Main.My Messages could cause issues, instead, use Main.MyMessages
50 {{/info}}
51
52 Alternatively you could also specify the list of Internationalization Document Bundles in ##xwiki.cfg## under the key ##xwiki.documentBundles##.
53
Silvia Macovei 6.2 54 = I18n of XWiki Objects =
Artem Melentyev 4.3 55
Thomas Mortagne 14.1 56 This is currently not implemented (see our logged issue: [[XWIKI-69>>https://jira.xwiki.org/browse/XWIKI-69]]). There are 2 workarounds you can use:
Silvia Macovei 6.1 57
Sergiu Dumitriu 8.1 58 * Have several objects, one for each language, with a language field, and then decide which object to use (for example in a Class Sheet, based on the current language):(((
59 {{code language="none"}}
60 $doc.getObject('Your.Class', 'lang', $context.language')
61 ## Will select the object whose 'lang' property is set to the current language
62 {{/code}}
63 )))
Vincent Massol 6.3 64 * Use Velocity scripting to do an IF in your object. For example, you could have:(((
Silvia Macovei 6.1 65 {{code language="none"}}
Vincent Massol 5.1 66 #if ($context.language == "fr")
67 French texts
68 #else
69 Default texts
70 #end
Silvia Macovei 6.1 71 {{/code}}
Vincent Massol 6.3 72 )))
Vincent Massol 10.1 73
Manuel Leduc 20.1 74 = I18n of XWiki Macros =
75
Manuel Leduc 20.2 76 To internationalize macros, the keys below can be added to the Translation document as [[presented above>>#HUsingpropertieslocatedinXWikipages]].
Manuel Leduc 20.1 77 A concrete example is presented in the [[Macro Tutorial>>Documentation.DevGuide.Tutorials.WritingMacros.WikiMacroTutorial]].
78
79 {{code}}
80 rendering.macro.<macro id>.name=Name of the macro, displayed in the macros list in the macros wizard
81 rendering.macro.<macro id>.description=Description of the macro, displayed as a help in the macros list in the macros wizard
82
83 rendering.macro.<macro id>.parameter.<parameter name>.name=Name of the macro parameter, to be displayed in the form for the macro settings in the macros wizard
84 rendering.macro.<macro id>.parameter.<parameter name>.description=Description of the macro parameter, to be displayed as a help in the form for the macro settings in the macros wizard
85 {{/code}}
86
Vincent Massol 10.1 87 = Using the static Resource Bundles =
88
89 * Stop your XWiki instance
Manuel Smeria 11.3 90 * Extract the ##ApplicationResources*.properties## file for your language from the ##WEB-INF/lib/xwiki-*oldcore-*.jar## file and put them in your ##WEB-INF/classes## directory
91 * Edit this file and add/modify the key/value pairs you need for your application
Clemens Robbenhaar 11.5 92 * In your document, use the following to get the value associated with a key: {{code language="none"}}$services.localization.render("key"){{/code}}
Vincent Massol 10.1 93
94 This will get the value from the Resource Bundle corresponding to the current language you are using in XWiki.
Vincent Massol 13.1 95
Manuel Leduc 20.2 96 If you're writing an extension JAR and wish to have static translation resources, you can put them in a ##ApplicationResources*.properties## file at the root of your extension JAR and they'll get picked up by the Localization module. See the [[Localization module>>extensions:Extension.Localization Module#HProvidetranslationbundleinajar]] for more details.

Get Connected