Front-end Localization WebJar
Reference
xwiki-platform-localization-webjar exposes the front-end localization to the browser. It applies initialize to the XWiki REST translator of the current wiki and exports the resulting Resolver, 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.
resolver
XWiki 18.3.0+ 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.
const resolver: Resolver;The translations are keyed by the full translation key, prefix included.
import { resolver } from "xwiki-platform-localization-webjar";
const { translations, missed } = await resolver.resolve({
prefix: "livedata.",
keys: ["dropdownMenu.title", "selection.infoBar.allSelectedBut"],
});
console.log(translations["livedata.dropdownMenu.title"]);It is also the value the Vue adapter expects as its first parameter.
import { useI18nAdapter } from "@xwiki/platform-localization-adapter-vue";
import { resolver } from "xwiki-platform-localization-webjar";
const { t, isLoading } = useI18nAdapter(resolver, {
prefix: "livedata.",
keys: ["dropdownMenu.title"],
});xwiki-l10n
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.
| Member | Description |
|---|---|
| [key] | The translation of key, with the query prefix removed. |
| 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. |
define("my-translation-keys", {
prefix: "livedata.",
keys: ["dropdownMenu.title", "selection.infoBar.allSelectedBut"]
});
require(["xwiki-l10n!my-translation-keys"], function (l10n) {
console.log(l10n["dropdownMenu.title"]);
console.log(l10n.get("selection.infoBar.allSelectedBut", "parameter value"));
});Importmap
{
"xwiki-platform-localization-webjar": "org.xwiki.platform:xwiki-platform-localization-webjar/index.es.js"
}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.
Dependency
<dependency>
<groupId>org.xwiki.platform</groupId>
<artifactId>xwiki-platform-localization-webjar</artifactId>
<version>${project.version}</version>
<scope>runtime</scope>
</dependency>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 leaves it external already, and a WebJar with its own Vite configuration declares it explicitly.
export default defineConfig({
build: {
rollupOptions: {
external: ["xwiki-platform-localization-webjar"],
},
},
});FAQ
Where do the translations come from?
From the localization/translations REST endpoint of the current wiki, which returns the raw source of each requested key.
Should I use resolver or xwiki-l10n?
Use resolver from ES modules, and the xwiki-l10n loader plugin from the code still loaded through RequireJS.
How do I translate the keys of a Vue component?
Pass resolver to the Vue adapter, which turns it into a vue-i18n translation function.
