The Placer Toolkit alpha has arrived! 🎉
Plenty of changes are coming your way—some big, some breaking, some even nuclear! Beware the changelog…

Bring it on!

Localisation

Components can be localised by importing the appropriate translation file and setting the desired lang attribute and/or dir attribute on the <html> element. Here’s an example that renders Placer Toolkit components in French.

<!DOCTYPE html>
<html lang="fr">
    <head>
        <!-- … -->
        <script type="module" src="/path-to-placer-toolkit/dist/translations/fr.js"></script>
    </head>
    <body>
        <!-- … -->
    </body>
</html>

Through the magic of a mutation observer, changing the lang attribute will automatically update all localised components to use the new locale.

Available translations#

Placer Toolkit ships with a number of translations. The default is English (United States), which also serves as the fallback locale. As such, you do not need to import the English translation.

We will list the available translations categorised by language family.

Indo‐European family#

Germanic#

Dansk (da)
Deutsch (de)
Deutsch (Österreich) (de-at)
Deutsch (Schweiz) (de-ch)
English (en)
English (United Kingdom) (en-gb)
Føroyskt (fo)
Íslenska (is)
Lëtzebuergesch (lb)
Nederlands (nl)
Nederlands (België) (nl-be)
Norsk bokmål (nb)
Norsk nynorsk (nn)
Svenska (sv)

Romance#

Català (ca)
Español (España) (es-es)
Español (Latinoamérica) (es-419)
Français (fr)
Français (Canada) (fr-ca)
Italiano (it)
Română (ro)
Português Brasileiro (pt-br)
Português Europeu (pt-pt)

Slavic#

Български (bg)
Bosanski (bs)
Čeština (cs)
Hrvatski (hr)
Polski (pl)
Русский (ru)
Slovenčina (sk)
Slovenščina (sl)
Српски (sr)
Українська (uk)

Indo‐Aryan/Indic#

বাংলা (bn)
ગુજરાતી (gu)
हिन्दी (hi)
मराठी (mr)
پنجابی (pa)
ਪੰਜਾਬੀ (ਗੁਰਮੁਖੀ) (pa-guru)
اردو (ur)

Celtic#

Cymraeg (cy)
Gaeilge (ga)

Hellenic#

Ελληνικά (el)

Albanian#

Shqip (sq)

Baltic#

Lietuvių (lt)
Latviešu (lv)

Iranian#

فارسی (fa)
پښتو (ps)

East Asian#

Sino‐Tibetan#

简体中文 (zh-cn)
繁體中文（香港） (zh-hk)
繁體中文（台灣） (zh-tw)

Japonic#

日本語 (ja)

Koreanic#

한국어 (ko)

Afro‐Asiatic family#

Semitic/Berber#

العَرَبِيَّة (ar)
עברית (he)
Malti (mt)

Austronesian family#

Sunda‐Sulawesi#

Filipino (fil)
Bahasa Indonesia (id)
Melayu (ms)
Tagalog (tl)

Uralic family#

Finnic/Ugric#

Eesti (et)
Suomi (fi)
Magyar (hu)

Turkic family#

Oghuz#

Türkçe (tr)

Tai‐Kadai family#

Tai#

ລາວ (lo)
ไทย (th)

Dravidian family#

South‐Central#

తెలుగు (te)

Austroasiatic family#

Vietic#

Tiếng Việt (vi)

Niger‐Congo family#

Bantu#

Kiswahili (sw)

Language isolate#

Basque#

Euskara (eu)

The location of translations depend on how you’re using Placer Toolkit. If you’re using the CDN, import them from the CDN. If you’re instead using a bundler, import them from placer-toolkit/dist/translations/[lang].js, respectively.

You do not need to load translations up front. You can import them dynamically even after updating the lang attribute. Once a translation is registered, localised components will update automatically.

// Same as setting <html lang="de">
document.documentElement.lang = "de";

// Import the translation
import("/path-to-placer-toolkit/dist/translations/de.js");

Translation resolution#

The locale set by <html lang="…"> is the default locale for the document. If a country code is provided, e.g., fr-CA for French (Canada), the localisation utility will resolve it like this:

Look for fr-CA
Look for fr
Fall back to en

Placer Toolkit uses English (United States) as a fallback to provide a better experience than rendering nothing or throwing an error.

Submitting new translations or improvements#

To contribute new translations or improvements to existing translations, please submit a pull request on GitHub. Translations are located in src/translations and can be edited directly on GitHub if you don’t want to clone the repository locally.

Regional translations are welcome! For example, if a German translation (de) exists, it’s perfectly fine to submit a Swiss German (de-CH) translation.

Placer Toolkit provides a localisation mechanism for component internals. This is not designed to be used as a localisation tool for your entire application. You should use a more appropriate tool such as i18next if you need to localise content in your app.

Multiple locales per page#

You can use a different locale for an individual component by setting its lang and/or dir attributes. Here’s an example to demonstrate this.

<!DOCTYPE html>
<html lang="es">
    <head>
        <!-- … -->
        <script type="module" src="/path-to-placer-toolkit/dist/translations/es.js"></script>
        <script type="module" src="/path-to-placer-toolkit/dist/translations/ru.js"></script>
    </head>
    <body>
        <pc-button><!-- Spanish --></pc-button>
        <pc-button lang="ru"><!-- Russian --></pc-button>
    </body>
</html>

For performance reasons, the lang and dir attributes must be on the component itself, not on an ancestor element. But this doesn’t apply if you place the attributes on the <html> element.

<!DOCTYPE html>
<html lang="es">
    <head>
        <!-- … -->
        <script type="module" src="/path-to-placer-toolkit/dist/translations/es.js"></script>
        <script type="module" src="/path-to-placer-toolkit/dist/translations/ru.js"></script>
    </head>
    <body>
        <div lang="ru">
            <pc-button><!-- Still in Spanish --></pc-button>
        </div>
    </body>
</html>

This limitation exists because there isn’t an efficient way to determine the current locale of a given element in a DOM tree. We think this is a gap in the platform and this GitHub issue wants to propose a couple properties to make this possible.

Creating your own translations#

You can provide your own translations if you have specific needs or if you don’t want to wait for a translation to land upstream. The easiest way to do this is to copy src/translations/en.ts into your own project and translate the terms inside. When your translation is done, you can import it and use it just like a built‐in translation.

Let’s create a Spanish (Spain) translation as an example. The following example assumes that you’re using TypeScript, but you can also create translations with regular JavaScript.

import { registerTranslation } from "placer-toolkit/dist/translations/index.js";
import type { Translation } from "placer-toolkit/dist/utilities/localize.js";

const translation: Translation = {
    $code: "es-es",
    $name: "Español (España)",
    $dir: "ltr",

    carousel: "Carrusel",
    clearEntry: "Borrar entrada",
    close: "Cerrar",
    copied: "¡Copiado!",
    copy: "Copiar",
    currentValue: "Valor actual",
    error: "Error",
    goToSlide: (slide, count) => `Ir a la diapositiva ${slide} de ${count}`,
    hidePassword: "Ocultar contraseña",
    loading: "Cargando…",
    nextSlide: "Siguiente diapositiva",
    numOptionsSelected: (number) => {
        if (number === 0) {
            return "No hay opciones seleccionadas";
        } else if (number === 1) {
            return "Una opción seleccionada";
        } else {
            return `${number} opciones seleccionadas`;
        }
    },
    pickAColorFromTheScreen: "Seleccionad un color de la pantalla",
    previousSlide: "Diapositiva anterior",
    progress: "Progreso",
    remove: "Eliminar",
    resize: "Cambiar tamaño",
    scrollableRegion: "Región desplazable",
    scrollToEnd: "Desplazaos hasta el final",
    scrollToStart: "Desplazaos al inicio",
    showPassword: "Mostrar contraseña",
    slideNum: (slide) => `Diapositiva ${slide}`,
    toggleColorFormat: "Alternar el formato de color",
};

registerTranslation(translation);

export default translation;

Once your translation has been compiled to JavaScript, import and activate it like this.

<!DOCTYPE html>
<html lang="es">
    <head>
        <!-- … -->
        <script type="module" src="/path-to-translation/es.js"></script>
    </head>
    <body>
        <!-- … -->
    </body>
</html>

If your translation isn’t working, make sure you’re using the same localisation module when importing registerTranslation. If you’re using a different module, your translation won’t be recognised.