Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/DenysVuika/preact-translate
Minimalistic translate (i18n) library for Preact
https://github.com/DenysVuika/preact-translate
i18n preact preact-components preact-x translation typescript
Last synced: about 2 months ago
JSON representation
Minimalistic translate (i18n) library for Preact
- Host: GitHub
- URL: https://github.com/DenysVuika/preact-translate
- Owner: DenysVuika
- License: mit
- Created: 2019-07-17T12:46:02.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2024-01-20T21:44:38.000Z (11 months ago)
- Last Synced: 2024-07-19T01:22:16.458Z (5 months ago)
- Topics: i18n, preact, preact-components, preact-x, translation, typescript
- Language: TypeScript
- Size: 3.22 MB
- Stars: 64
- Watchers: 3
- Forks: 6
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
- awesome-preact - Preact Translate - Minimalistic translate (i18n) library for Preact. (Uncategorized / Uncategorized)
README
# preact-translate
Minimalistic translate (i18n) library for Preact
[](https://dev.azure.com/denysvuika/preact-translate/_build/latest?definitionId=3&branchName=master)
Bundle size: ~1KB
Live example: [Sandbox](https://codesandbox.io/embed/preact-translate-npm-tpe4f)
## Installing
Minimal requirements: **Preact 10.0.0**
Add the `.npmrc` file to your project root if you are using [GitHub Package Registry](https://help.github.com/en/articles/about-github-package-registry)
```yaml
registry=https://npm.pkg.github.com
```
Using Yarn:
```sh
yarn add @denysvuika/preact-translate
```
Using NPM:
```sh
npm i @denysvuika/preact-translate
```
## Basic usage
You should wrap your application with the `TranslateProvider` component:
```jsx
import { TranslateProvider } from '@denysvuika/preact-translate';
export default function App() {
return (
);
}
```
Create an `assets/en.json` file with the following content:
```json
{
"title": "Hello",
"subtitle": "World"
}
```
Create a second file `assets/ua.json` to be able to switch between different resources.
```json
{
"title": "[ua] Hello",
"subtitle": "[ua] World"
}
```
You can now use the `TranslateContext` in your components to access the translation API and data:
```jsx
import { useContext } from 'preact/hooks';
import { TranslateContext } from '@denysvuika/preact-translate';
export default function MainComponent() {
const { setLang, t, lang } = useContext(TranslateContext);
return (
Lang: {lang}
{t('title')}
{t('subtitle')}
setLang('en')}>EN
setLang('ua')}>UA
);
}
```
For the `EN` locale you should see:
```text
Lang: en
Hello
World
```
For the `UA` locale you should see:
```text
Lang: ua
[ua] Hello
[ua] World
```
The language loading performs on demand.
The `en.json` gets loaded and cached only when first requested by your application.
## Configuring assets root folder
By default, the `assets` folder is used to fetch locales.
You can change it via the `TranslateProvider.root` property:
```jsx
import { TranslateProvider } from '@denysvuika/preact-translate';
export default function App() {
return (
);
}
```
## Formatted translations
You can use runtime string substitution when translating text
```json
{
"hello": "Hello, {name}"
}
```
Then in the JSX:
```jsx
{t('hello', { name: 'Bob' })}
```
## Nested translations
The library supports complex objects with nested levels.
Put the following in the `en.json` file:
```json
{
"messages": {
"errors": {
"404": "Sorry, not found"
}
}
}
```
Then in the JSX use:
```jsx
{t('messages.errors.404')}
```
You can also use composite strings like the following:
```json
{
"messages.errors.404": "Sorry, not found"
}
```
## Default language
You can set the default language to use with the application by assigning the `TranslateProvider.lang` property.
```html
```
Please note that in this case provider is going to load and cache two locales at startup:
`en.json` (as a fallback) and `ua.json` (as an active lang).
## Custom translation data
You can use `TranslateProvider.translations` property to provide a custom translation data from the code.
That helps with unit testing as well.
```jsx
const data = {
en: {
messages: {
404: 'Not found'
}
}
};
;
```
Note that the `TranslateProvider` is not going to fetch translation files for the `en` locale,
and will use your custom data instead.