;\n```\n\n## Template Syntax Summary\n\nWe've seen that `%\\d+` introduces a placeholder into a template string. Placeholders may optionally be followed by `[text in brackets]` that will be available to child components. There may be no spaces between the placeholder and the opening `[`.\n\nTo interpolate the contents of a translation from the dictionary we use `%{tagName}`.\n\nA `%` followed by `%`, `[` or `]` escapes that character:\n\n- for `%` use `%%`\n- for `[` after a placeholder use `%[`\n- for `]` inside placeholder text use `%]`\n\nThe brackets `[` and `]` are only special after a placeholder - you can use them anywhere else without escaping them.\n\nApart from their use in `%{tagName}` `{` and `}` also have no special significance and may be used unescaped.\n\nAny `%` that isn't followed by a digit or `%`, `[` or `]` is passed through unaltered so for most text you won't have to worry about escaping special characters.\n\n# Plurals: Let's Count Cats!\n\nDifferent languages have different rules for forming plurals. They also have different kinds of plurals: Welsh has six. Here's how we count cats in English, German and Welsh\n\n```js\n// A pluralised, templated fat string.\nconst cats = {\n en: { one: \"%1 cat\", other: \"%1 cats\" },\n de: { one: \"%1 Katze\", other: \"%1 Katzen\" },\n cy: {\n zero: \"%1 cathod\",\n one: \"%1 gath\",\n two: \"%1 gath\",\n few: \"%1 cath\",\n many: \"%1 chath\",\n other: \"%1 cath\"\n }\n};\n\nfunction Cats({ count }) {\n // We stringify count because otherwise when we try to count 0 cats\n // React treats the falsy 0 as a non-existent component because 0 is\n // false but \"0\" is true.\n return (\n \n {String(count)}\n \n );\n}\n\nfunction CountCats() {\n const counts = [0, 1, 1.5, 2, 3, 6, 42];\n return (\n \n {counts.map((count, i) => (\n \n ))}\n
\n );\n}\n\n// You're here for the Welsh cats, right?\n// 0 cathod\n// 1 gath\n// 1.5 cath\n// 2 gath\n// 3 cath\n// 6 chath\n// 42 cath\n```\n\nThe `count` property of `T` is used select the language-appropriate plural.\n\nPlurals don't have to be templated but it's often a good idea because it allows the translator to vary where the number appears in the text.\n\n# Use with Intl\n\nThe [ECMAScript Internationalization API](https://tc39.es/ecma402/#intl-object) provides language sensitive string comparison, number formatting, date and time formatting, pluralisation rules and more. With the exception of pluralisation _Interminimal_ doesn't attempt to wrap any of the `Intl` APIs but it does make it easy to work with them. It's a conscious decision not attempt to integrate `Intl` functionality more tightly:\n\n- locales vary by browser and may differ from Node's implementation\n- `Intl` support isn't complete across all browsers\n- _Interminimal_ is supposed to be minimal\n- it's easy to use `Intl` with _Interminimal_ so why abstract it further?\n\nBear in mind when using the `Intl` APIs that locale and feature support varies by browser and will also likely be different between NodeJS and any particular browser. That can cause problems for Server Side Rendering - for example, at the time of writing, Node 18 has support for Welsh Date/Time formatting but Chrome does not. An SSR Welsh page will therefore render date / time strings differently on initial render and hydration.\n\nYou can test browser support for the languages you're interested in using the [Language Stack Calculator](https://bbcni.github.io/Interminimal/demo/calculator).\n\nWith that caveat `Intl` is extremely useful so let's see how it works. Here's a component that wraps `Intl.DateTimeFormat`:\n\n```js\nconst TDateFormat = ({ date, ...opt }) => {\n const ctx = useTranslation();\n // Use our languages stack to find a format for our locale\n const dtf = new Intl.DateTimeFormat(ctx.languages, opt);\n // Find out which language was matched...\n const { locale } = dtf.resolvedOptions();\n // Format the date and create a literal ts with the available\n // locale\n const ts = TString.literal(dtf.format(date), locale);\n // Format it using T\n return ;\n};\n```\n\nWe use it like this:\n\n```js\nreturn ;\n```\n\nMost of the `Intl` APIs can be wrapped into components in a similar way. For example here's a component that wraps `Intl.ListFormat`. It translates the formatting of lists of items (`\"This, that, and something else\"`).\n\n```js\nconst TList = ({ children, ...opt }) => {\n const ctx = useTranslation();\n // Use our languages stack to find a format for our locale\n const lf = new Intl.ListFormat(ctx.languages, opt);\n // Find out which language was matched...\n const { locale } = lf.resolvedOptions();\n // Make the children into a list of args, %1, %2 etc\n const list = Array.from(\n { length: Children.count(children) },\n (_v, i) => `%${i + 1}`\n );\n\n // Format the list into a template string and make the translated\n // template and locale into a TString\n const ts = TString.literal(lf.format(list), locale);\n // Format it using T\n return {children};\n};\n```\n\nUse it like this:\n\n```js\nreturn (\n \n \n \n \n \n);\n// en: One, Two, and Three\n// de: Eins, zwei und drei\n```\n\nGenerally speaking the pattern is\n\n- attempt to create an instance of the API for our preferred languages\n- check which locale was actually found\n- format our data using the API\n- wrap it in a `TString` with the correct lang (`locale`)\n- render it with ``\n\nA similar technique is likely to work with internationalisation APIs other than `Intl`.\n\n# Summary\n\n`Translate` creates a translation context. Any use of `T` in components below the `Translate` will attempt to translate text according to the context settings. `Translate` can be nested to any depth. Each `Translate` inherits and potentially overrides settings from its parent context. The most interesting properties of a translation context are `lang`, `defaultLang` and `dictionary`.\n\n`T` attempts to translate text in fat strings or from the dictionary. It can translate content and properties. By default `T` renders as a span but it can be asked to render as any element or component.\n\n`T` supports plurals and templating. Templating can nest to any depth. Templates can re-order child components.\n\nYou can read more in the [API documentation](https://bbcni.github.io/Interminimal/modules.html).\n\n# CI Status\n\n[](https://github.com/BBCNI/Interminimal/actions/workflows/node.js.yml)\n\n[](https://github.com/BBCNI/Interminimal/actions/workflows/codeql-analysis.yml)\n\n# License\n\n[MIT](LICENSE)\n","readmeFilename":"README.md","homepage":"https://bbcni.github.io/Interminimal","keywords":["react","translation","internationalisation","i18n","welsh","plurals","typescript"],"repository":{"type":"git","url":"git+https://github.com/BBCNI/Interminimal.git"},"author":{"name":"Andy Armstrong","email":"andy@hexten.net"},"bugs":{"url":"https://github.com/BBCNI/Interminimal/issues"},"license":"MIT"}