preact-i18n
Advanced tools
Simple localization for Preact.
{{fields}} in definition valuesBy 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.
npm install --save preact-i18n
# For TypeScript Definitions
npm install --save-dev @types/preact-i18n
fr.json:{
"news": {
"title": "Nouvelles du Monde",
"totalStories": {
"none": "Aucun article",
"one": "Un article",
"many": "{{count}} articles"
}
}
}
<IntlProvider>:import { IntlProvider } from 'preact-i18n';
import definition from './fr.json';
render(
<IntlProvider definition={definition}>
<App />
</IntlProvider>
);
<Text /> to translate string literals:import { Text } from 'preact-i18n';
// Assume the "stories" prop is a list of news stories.
const App = ({ stories=[] }) => (
<div class="app">
<h1>
{/* Default fallback text example: */}
<Text id="news.title">World News</Text>
</h1>
<footer>
{/* Pluralization example: */}
<Text
id="news.totalStories"
plural={stories.length}
fields={{
count: stories.length
}}
/>
</footer>
</div>
);
That's it!
Rendering our example app with an empty definition (or without the Provider) will attempt to use any text contained within <Text>..</Text> as fallback text.
In our example, this would mean rendering without a definition for news.title would produce <h1>World News</h1>.
If we provide a definition that has a title key inside a news object, that value will be rendered instead.
In our example, <footer> is using <Text> 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 <Text>.
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": ["apples", "apple"]Taking <Text id="news.totalStories" ..> 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 articlesIn addition to <Text>, withText() and <Localizer> provide ways to translate more than just display text - HTML attributes, component props, arbitrary Strings, etc.
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.
<IntlProvider> 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
<IntlProvider>, but still remain localizable by their parent components.
props
props.scope String? Nest definition under a root key, and set the active scope for the tree (essentially prefixing all <Text /> keys).props.mark Boolean If true, all <Text> 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 {})// generally imported from a JSON file:
let definition = {
foo: 'Le Feux'
};
<IntlProvider scope="weather" definition={definition}>
<Text key="foo">The Foo</Text>
</IntlProvider>
// This will render the text:
"Le Feux"
<Localizer /> is a Compositional Component.
It "renders" out any <Text /> values in its child's props.
props Object
props.children Object Child components with props to localize.context Object
context.intl Object [internal] dictionary and scope info<Localizer>
<input placeholder={<Text id="username.placeholder" />} />
</Localizer>
// produces:
<input placeholder="foo" />
<Localizer>
<abbr title={<Text id="oss-title">Open Source Software</Text>}>
<Text id="oss">OSS</Text>
</abbr>
</Localizer>
// produces:
<abbr title="Open Source Software">OSS</abbr>
<MarkupText> is just like Text but it can also contain html markup in rendered strings. It wraps its contents in a <span> tag.
props Object 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 <Text/> nodes which will be resolved to their translated value (optional, default {})props.plural Number? Integer "count", used to select plural formscontext Object
context.intl Object [internal] dictionary and scope info// If there is no dictionary in context..
<MarkupText id="foo"><b>The Foo</b></MarkupText>
// ..produces the vnode:
<span><b>The Foo</b></span>
// Given a dictionary and some fields..
<IntlProvider definition={{ foo:'Le Feux <b>{{bar}}</b>' }}>
<MarkupText id="foo" fields={{ bar: 'BEAR' }}>The Foo</MarkupText>
</IntlProvider>
// ..produces the vnode:
<span>Le Feux <b>BEAR</b></span>
// Within a scope, both `id` and the definition are namespaced..
<IntlProvider scope="weather" definition={{ foo:'Le <a href="http://foo.com">Feux</a>' }}>
<MarkupText id="foo">The Foo</MarkupText>
</IntlProvider>
// ..produces the vnode:
<span>Le <a href="http://foo.com">Feux</a></span>
// renders nothing if there is no key match and no fallback
<div><MarkupText /></div>
// ..produces the vnode:
<div/>
<Text> 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 the fields prop.
When string lookup fails, renders its children as fallback text.
props Object props
props.id String Key to look up in intl dictionary, within any parent scopes ($scope1.$scope2.$id)props.children ReactElement? Fallback text if no definition is foundprops.plural Number? Integer "count", used to select plural formsprops.fields Object Values to inject into template {{fields}}. Values in the fields object will be coerced to strings, with the exception of <Text/> nodes which will be resolved to their translated value (optional, default {})// If there is no dictionary in context..
<Text id="foo">The Foo</Text>
// ..produces the text:
"The Foo"
// Given a dictionary and some fields..
<IntlProvider definition={{ foo:'Le Feux {{bar}}' }}>
<Text id="foo" fields={{ bar: 'BEAR' }}>The Foo</Text>
</IntlProvider>
// ..produces the text:
"Le Feux BEAR"
// Within a scope, both `id` and the definition are namespaced..
<IntlProvider scope="weather" definition={{ foo:'Le Feux' }}>
<Text id="foo">The Foo</Text>
</IntlProvider>
// ..produces the text:
"Le Feux"
@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.
@withText({
placeholder: 'user.placeholder'
})
class Foo {
// now the `placeholder` prop is our localized String:
render({ placeholder }) {
return <input placeholder={placeholder} />
}
}
@withText({
placeholder: <Text id="user.placeholder">fallback text</Text>
})
class Foo {
render({ placeholder }) {
return <input placeholder={placeholder} />
}
}
@withText('user.placeholder')
class Foo {
// for Strings/Arrays, the last path segment becomes the prop name:
render({ placeholder }) {
return <input placeholder={placeholder} />
}
}
Works with functional components, too
const Foo = withText('user.placeholder')( props =>
<input placeholder={props.placeholder} />
)
getWrappedComponent() returns wrapped child Component
const Foo = () => <div/>;
const WrappedFoo = withText('user.placeholer')(Foo);
WrappedFoo.getWrappedComponent() === Foo; // true
useText is the hook version of withText
function MyComponent() {
const { placeholder } = useText({
placeholder: 'user.placeholder'
});
return <input placeholder={placeholder} />
}
function MyComponent() {
const { placeholder } = useText({
placeholder: <Text id="user.placeholder">fallback text</Text>
});
return <input placeholder={placeholder} />
}
function MyComponent() {
// for Strings/Arrays, the last path segment becomes the prop name:
const { placeholder } = useText('user.placeholder');
return <input placeholder={placeholder} />
}
Higher-order function that creates an <IntlProvider /> 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:
Childoptions Object If there are two arguments, the second argument is Passed as props to <IntlProvider />
options.scope Nest definition under a root key, and set the active scope for the tree (essentially prefixing all <Text /> 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 {})Attempts to look up a translated value from a given dictionary. Also supports json templating using the format: {{variable}} Falls back to default text.
id String Intl field name/id (subject to scope)scope String Scope, which prefixes id with ${scope}. (optional, default '')dictionary Object A nested object containing translationsfields Object Template fields for use by translated strings (optional, default {})plural Number? Indicates a quantity, used to trigger pluralizationfallback (String | Array)? Text to return if no translation is foundReturns String translated
FAQs
Preact internationalization, done simply.
The npm package preact-i18n receives a total of 3,227 weekly downloads. As such, preact-i18n popularity was classified as popular.
We found that preact-i18n demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
An advanced npm supply chain attack is leveraging Ethereum smart contracts for decentralized, persistent malware control, evading traditional defenses.
Security News
Research
Attackers are impersonating Sindre Sorhus on npm with a fake 'chalk-node' package containing a malicious backdoor to compromise developers' projects.
Security News
The npm package for the LottieFiles Player web component was hit with a supply chain attack after a software engineer's npmjs credentials were compromised.