git%2Bgithub.com%2Fsynacor%2Fpreact-i18n?ref=badge_shield)

Usage example

Simple localization for Preact.

- Tiny: about 1.3kb gzipped
- Supports dictionary and key scopes/namespaces while maintaining a global dictionary
- Supports nested dictionaries:
- Wrap your component in a default dictionary and scope key
- Wrap it again later on (in an app!) to override the defaults
- Supports pluralization of strings using nested objects.
- Supports template {{fields}} in definition values
- Has a companion ESLint plugin to help catch bugs early

- Installation
- Getting Started
- Fallback Text
- Pluralization and Templating
- ESLint Plugin
- API

Preact Version Support

By default, the master branch of this repo supports preact 9 and below, and is published in normal patch/minor/major releases to the latest tag in npm. Support for preact X (versions 10+ of preact) is handled in the preactX branch and are always published to the preactx tag in npm. When preact X obtains widespread adoption, the master branch of this project will support preact X and a new major version under latest tag will be published to in npm.

Installation

``sh npm install --save preact-i18n

`For TypeScript Definitions`


npm install --save-dev @types/preact-i18n


Getting Started

1. Create a definition. Typically JSON files, we'll call ours fr.json:

`json { "news": { "title": "Nouvelles du Monde", "totalStories": { "none": "Aucun article", "one": "Un article", "many": "{{count}} articles" } } }`

2. Expose the definition to your whole app via :

`js import { IntlProvider } from 'preact-i18n'; import definition from './fr.json';

render( );`

3. Use to translate string literals:

`js import { Text } from 'preact-i18n';

// Assume the "stories" prop is a list of news stories. const App = ({ stories=[] }) => (


		
			{/ Default fallback text example: /}
			World News
		

		
			{/ Pluralization example: /}
							id="news.totalStories"
				plural={stories.length}
				fields={{
					count: stories.length
				}}
			/>

);


That's it!
$3

Rendering our example app with an empty definition _(or without the Provider)_ will attempt to use any text contained within .. as fallback text.

In our example, this would mean rendering without a definition for news.title would produce

World News

.

If we provide a definition that has a title key inside a news object, that value will be rendered instead.

`$3`

In our example,

is using as a convenient way to do pluralization and templating. In our definition, news.totalStories is an Object with pluralization keys. The values in that object will be selected based on an integer plural prop passed to .

Any definition value _(including pluralization values)_ can contain {{field}} placeholders. These placeholders get replaced with matched keys in an object passed as the fields prop. In our example, the "many" plural form is such a template - it will render "5 articles" when fields={{ count: 5 }}.

The available forms for specifying pluralization values are as follows:

- "key": { "singular":"apple", "plural":"apples" }-"key": { "none":"no apples", "one":"apple", "many":"apples" }-"key": { "zero":"no apples", "one":"apple", "other":"apples" }-"key": ["apples", "apple"]

Taking from our example:

- <.. plural={0}> renders Aucun article_(no articles)_ -<.. plural={1}> renders Un article_(one article)_ -<.. plural={2} fields={{ count: 2 }}> renders 2 articles-<.. plural={3} fields={{ count: 3 }}> renders 3 articles

In addition to , withText() and provide ways to translate more than just display text - HTML attributes, component props, arbitrary Strings, etc.

`ESLint Plugin`

A companion ESLint plugin exists, eslint-plugin-preact-i18n, which has several rules that help spot common issues like un-i18n'd text, misconfigured tags, and missing keys, that are beneficial in spotting defects early and ensuring that your application is properly i18n'd.

*

`API`

#### Table of Contents

- IntlProvider - Parameters - Examples - Localizer - Parameters - Examples - MarkupText - Parameters - Examples - Text - Parameters - Examples - withText - Parameters - Examples - useText - Parameters - Examples - intl - Parameters - translate - Parameters

`$3`

is a nestable internationalization definition provider. It exposes an Intl scope & definition into the tree, making them available to descendant components.

> Note: When nested, gives precedence to keys higher up the tree! > This means lower-level components can set their defaults by wrapping themselves > in an, but still remain localizable by their parent components.

#### Parameters

- props-props.scope String? Nest definition under a root key, and set the active scope for the tree (essentially prefixing all keys). -props.mark Boolean If true, all elements will be shown with a red/green background indicating whether they have valid Intl keys. (optional, default false) -props.definition Object Merge the given definition into the current intl definition, giving the _current_ definition precedence (i.e., only adding keys, acting as defaults) (optional, default {})

#### Examples

`javascript // generally imported from a JSON file: let definition = { foo: 'Le Feux' };

The Foo

// This will render the text: "Le Feux"`

`$3`

is a Compositional Component. It "renders" out any values in its child's props.

#### Parameters

- propsObject -props.childrenObject Child components with props to localize. -contextObject -context.intl Object [internal] dictionary and scope info

#### Examples

`javascript } /> // produces:`

`javascript Open Source Software}> OSS // produces: OSS`

`$3`

is just like Text but it can also contain html markup in rendered strings. It wraps its contents in a tag.

#### Parameters

- propsObject props -props.id String Key to look up in intl dictionary, within any parent scopes ($scope1.$scope2.$id) -props.fields Object Values to inject into template {{fields}}. Values in the fields object will be coerced to strings, with the exception of nodes which will be resolved to their translated value (optional, default {}) -props.pluralNumber? Integer "count", used to select plural forms -props.children-props.props ...any

#### Examples

`javascript // If there is no dictionary in context.. The Foo // ..produces the vnode: The Foo`

`javascript // Given a dictionary and some fields.. {{bar}}' }}> The Foo // ..produces the vnode: Le Feux BEAR`

`javascript // Within a scope, bothidand the definition are namespaced.. Feux' }}> The Foo // ..produces the vnode: Le Feux`

`javascript // renders nothing if there is no key match and no fallback


// ..produces the vnode:

$3

renders internationalized text. It attempts to look up translated values from a dictionary in context.

Template strings can contain {{field}}placeholders, which injects values from thefields prop.

When string lookup fails, renders its children as fallback text.

#### Parameters

- propsObject props -props.id String Key to look up in intl dictionary, within any parent scopes ($scope1.$scope2.$id) -props.childrenReactElement? Fallback text if no definition is found -props.pluralNumber? Integer "count", used to select plural forms -props.fields Object Values to inject into template {{fields}}. Values in the fields object will be coerced to strings, with the exception of nodes which will be resolved to their translated value (optional, default {})

#### Examples

`javascript // If there is no dictionary in context.. The Foo // ..produces the text: "The Foo"`

`javascript // Given a dictionary and some fields.. The Foo // ..produces the text: "Le Feux BEAR"`

`javascript // Within a scope, bothidand the definition are namespaced.. The Foo // ..produces the text: "Le Feux"`

`$3`

@withText() is a Higher Order Component, often used as a decorator.

It wraps a child component and passes it translations based on a mapping to the dictionary & scope in context.

#### Parameters

- mapping (Object \| Function \| String) Maps prop names to intl keys (or nodes).

#### Examples

`javascript @withText({ placeholder: 'user.placeholder' }) class Foo { // now theplaceholderprop is our localized String: render({ placeholder }) { return } }`

`javascript @withText({ placeholder: fallback text }) class Foo { render({ placeholder }) { return } }`

`javascript @withText('user.placeholder') class Foo { // for Strings/Arrays, the last path segment becomes the prop name: render({ placeholder }) { return } }`

Works with functional components, too

`javascript const Foo = withText('user.placeholder')( props => )`

getWrappedComponent() returns wrapped child Component

`javascript const Foo = () =>

;
const WrappedFoo = withText('user.placeholer')(Foo);
WrappedFoo.getWrappedComponent() === Foo; // true

$3

useText is the hook version of withText

#### Parameters

- mapping (Object \| Function \| String) Maps prop names to intl keys (or nodes).

#### Examples

`javascript function MyComponent() { const { placeholder } = useText({ placeholder: 'user.placeholder' }); return }`

`javascript function MyComponent() { const { placeholder } = useText({ placeholder: fallback text }); return }`

`javascript function MyComponent() { // for Strings/Arrays, the last path segment becomes the prop name: const { placeholder } = useText('user.placeholder');

return }`

`$3`

Higher-order function that creates an wrapper component for the given component. It takes two forms depending on how many arguments it's given: It can take a functional form like: intl(ComponentToWrap, options)

or it can take an annotation form like:

#### Parameters

- Child-options Object If there are two arguments, the second argument is Passed as props to -options.scope Nest definition under a root key, and set the active scope for the tree (essentially prefixing all keys). -options.definition Merge the given definition into the current intl definition, giving the _current_ definition precedence (i.e., only adding keys, acting as defaults) (optional, default {})

`$3`

Attempts to look up a translated value from a given dictionary. Also supports json templating using the format: {{variable}} Falls back to default text.

#### Parameters

- idString Intl field name/id (subject to scope) -scope String Scope, which prefixes id with ${scope}. (optional, default '') -dictionaryObject A nested object containing translations -fields Object Template fields for use by translated strings (optional, default {}) -pluralNumber? Indicates a quantity, used to trigger pluralization -fallback` (String \| Array)? Text to return if no translation is found

Returns String translated

License

![FOSSA Status](https://app.fossa.io/projects/git%2Bgithub.com%2Fsynacor%2Fpreact-i18n?ref=badge_large)

preact-i18n

preact-i18n 🌎 ![npm](https://npm.im/preact-i18n) ![travis](https://travis-ci.org/synacor/preact-i18n) ![FOSSA Status](https://app.fossa.io/projects/git%2Bgithub.com%2Fsynacor%2Fpreact-i18n?ref=badge_shield)

Preact Version Support

Installation

For TypeScript Definitions

Getting Started

{/ Default fallback text example: /} World News

$3

World News

$3

Dist Tags

`For TypeScript Definitions`

{/ Default fallback text example: /}
World News

`$3`