Wiki source code of Front-end Localization WebJar
Last modified by Manuel Leduc on 2026/08/26 11:43
Hide last authors
| author | version | line-number | content |
|---|---|---|---|
 |
2.1 | 1 | ##xwiki-platform-localization-webjar## exposes the front-end localization to the browser. It applies [[initialize>>doc:documentation.xs.dev.front-end.localization.default.WebHome]] to the [[XWiki REST translator>>doc:documentation.xs.dev.front-end.localization.resolver-xwiki-rest.WebHome]] of the current wiki and exports the resulting [[Resolver>>doc:documentation.xs.dev.front-end.localization.api.WebHome]], so that front-end code obtains a working resolver without assembling a translator chain itself. It also provides ##xwiki-l10n##, the RequireJS loader plugin used by the code that is not loaded as an ES module. |
| 2 | |||
| 3 | == resolver == | ||
| 4 | |||
| 5 | {{version since="18.3.0RC1"}} | ||
| 6 | The resolver of the current wiki. It resolves the keys of a query against the ##localization/translations## REST endpoint of the wiki the page belongs to, in the locale of the request context, and returns the translations together with the keys it could not resolve. | ||
| 7 | {{/version}} | ||
| 8 | |||
| 9 | {{code language="typescript"}} | ||
| 10 | const resolver: Resolver; | ||
| 11 | {{/code}} | ||
| 12 | |||
| 13 | The translations are keyed by the full translation key, prefix included. | ||
| 14 | |||
| 15 | {{code language="typescript"}} | ||
| 16 | import { resolver } from "xwiki-platform-localization-webjar"; | ||
| 17 | |||
| 18 | const { translations, missed } = await resolver.resolve({ | ||
| 19 | prefix: "livedata.", | ||
| 20 | keys: ["dropdownMenu.title", "selection.infoBar.allSelectedBut"], | ||
| 21 | }); | ||
| 22 | console.log(translations["livedata.dropdownMenu.title"]); | ||
| 23 | {{/code}} | ||
| 24 | |||
| 25 | It is also the value the [[Vue adapter>>doc:documentation.xs.dev.front-end.localization.adapter-vue.WebHome]] expects as its first parameter. | ||
| 26 | |||
| 27 | {{code language="typescript"}} | ||
| 28 | import { useI18nAdapter } from "@xwiki/platform-localization-adapter-vue"; | ||
| 29 | import { resolver } from "xwiki-platform-localization-webjar"; | ||
| 30 | |||
| 31 | const { t, isLoading } = useI18nAdapter(resolver, { | ||
| 32 | prefix: "livedata.", | ||
| 33 | keys: ["dropdownMenu.title"], | ||
| 34 | }); | ||
| 35 | {{/code}} | ||
| 36 | |||
| 37 | == xwiki-l10n == | ||
| 38 | |||
| 39 | A RequireJS loader plugin, registered by ##l10n.es.js##, which the Flamingo skin loads on every page. The name after the ##!## is the identifier of a RequireJS module holding the query, either an array of full translation keys or an object with ##keys## and an optional ##prefix##. | ||
| 40 | |||
| 41 | |=Member|=Description | ||
| 42 | |##[key]##|The translation of ##key##, with the query prefix removed. | ||
| 43 | |##get(key, ...args)##|The translation of ##key## with its indexed placeholders replaced by ##args##, or ##null## when the key was not resolved. Doubled single quotes are unescaped as soon as one argument is passed. | ||
| 44 | |||
| 45 | {{code language="javascript"}} | ||
| 46 | define("my-translation-keys", { | ||
| 47 | prefix: "livedata.", | ||
| 48 | keys: ["dropdownMenu.title", "selection.infoBar.allSelectedBut"] | ||
| 49 | }); | ||
| 50 | |||
| 51 | require(["xwiki-l10n!my-translation-keys"], function (l10n) { | ||
| 52 | console.log(l10n["dropdownMenu.title"]); | ||
| 53 | console.log(l10n.get("selection.infoBar.allSelectedBut", "parameter value")); | ||
| 54 | }); | ||
| 55 | {{/code}} | ||
| 56 | |||
| 57 | == Importmap == | ||
| 58 | |||
| 59 | {{code language="javascript"}} | ||
| 60 | { | ||
| 61 | "xwiki-platform-localization-webjar": "org.xwiki.platform:xwiki-platform-localization-webjar/index.es.js" | ||
| 62 | } | ||
| 63 | {{/code}} | ||
| 64 | |||
| 65 | The mapping is declared by the WebJar itself, so a consuming extension does not repeat it in its own ##xwiki.extension.javascript.modules.importmap## property. See the [[JavaScript Importmap API>>doc:documentation.xs.dev.javascript.importmap.WebHome]]. | ||
| 66 | |||
| 67 | == Dependency == | ||
| 68 | |||
| 69 | {{code language="xml"}} | ||
| 70 | <dependency> | ||
| 71 | <groupId>org.xwiki.platform</groupId> | ||
| 72 | <artifactId>xwiki-platform-localization-webjar</artifactId> | ||
| 73 | <version>${project.version}</version> | ||
| 74 | <scope>runtime</scope> | ||
| 75 | </dependency> | ||
| 76 | {{/code}} | ||
| 77 | |||
| 78 | The module is resolved in the browser through the importmap, so it must stay out of the consuming bundle. A WebJar built with the [[shared Vite configuration>>doc:documentation.xs.dev.front-end.tools.vite-shared-configurations.WebHome]] leaves it external already, and a WebJar with its own Vite configuration declares it explicitly. | ||
| 79 | |||
| 80 | {{code language="typescript"}} | ||
| 81 | export default defineConfig({ | ||
| 82 | build: { | ||
| 83 | rollupOptions: { | ||
| 84 | external: ["xwiki-platform-localization-webjar"], | ||
| 85 | }, | ||
| 86 | }, | ||
| 87 | }); | ||
| 88 | {{/code}} |
