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 (almost 5 years ago)
• Default Branch: master
• Last Pushed: 2024-01-20T21:44:38.000Z (6 months ago)
• Last Synced: 2024-05-06T20:03:00.338Z (2 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

Lists

• awesome-preact - Preact Translate - Minimalistic translate (i18n) library for Preact. (Uncategorized / Uncategorized)
• awesome-stars - preact-translate

README

        
# preact-translate

Minimalistic translate (i18n) library for Preact

[![Build Status](https://dev.azure.com/denysvuika/preact-translate/_apis/build/status/DenysVuika.preact-translate?branchName=master)](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.