X i18n

What is it?

A React library that use hooks to internationalize the messages of your app. See a demo here.

Using X i18n

npm i @seudev/x-i18n

Messages Files

Create a folder with your message files.

• The file name must be the ISO language code;
• The default export must be the message object;
• The id property (required) must be the ISO language code (Equal to the file name);
• The messages property (required) must be a object.

The children of the messages property are your messages. You are free to define any structure. The message id is the path to access the message. Example: foo.bar

src/i18n/en.js

export default {
    id: "en",
    messages: {
        foo: {
            bar: "Hello World!"
        }
    }
};

src/i18n/pt-BR.js

export default {
    id: "pt-BR",
    messages: {
        foo: {
            bar: "Olá Mundo!"
        }
    }
};

I18n

import I18n from '@seudev/x-i18n';

Props

| Name | Type | Default | Description | | ------------------- | --------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | lang | string | | The lang that will be used. Must be one of available languages (langs). | | tryUseNavigatorLang | boolean | false | Tries use the navigator language. It verifies if the navigator language is available in the langs property. | | config | object | | An object with the fallback, an array of available languages (langs) and function that import the message files of lazy mode (messagesProvider). Note: The fallback message file must contain all messages of your application. |

Initialization

Using the I18n component:

• Import your message file that will be the fallback (See import en from './i18n/en').
• Initialize the x-i18n in your App class using the I18n component.

import React, { Component } from 'react';

import I18n from '@seudev/x-i18n';
import en from './i18n/en';

const i18nConfig = {
    fallback: en,
    langs: ['en', 'pt-BR'],
    messagesProvider: lang => import(`./i18n/${lang}`)
};

const App = props => {
    return (
        <I18n config={i18nConfig}>
            //Put your code here
        </I18n>
    );
};

export default App;

Using the useI18n hook:

| Property | Type | Description | | ------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | lang | string | The current language. | | langs | string[] | The available languages | | setLang | function(lang) | Sets the current language. | | tryUseNavigatorLang | function() | Try use the navigator language | | getMessage | function(id, params = {}, defaultMessage) | Gets a interpolated message associated of given id. If pass an array will be used the first found message. | | formatDate | function(date, options, lang) | Formats a given date. |

• Import the useI18n hook
• Invoke the useI18n hook inside your component
• Use the returned properties that you desires

import { useI18n } from '@seudev/x-i18n';

const MyComponent = props => {
    const { lang, langs, setLang, tryUseNavigatorLang, getMessage, formatDate } = useI18n();

    return (
        //Use the hook properties
    )

}

Set Lang

Using the I18n component:

    <I18n lang="pt-BR" />

Note: You can use the lang property together with the initialization.

Using the useI18n hook:

import { useI18n } from '@seudev/x-i18n';

export default props => {
    const { setLang } = useI18n();

    return (
        <div>
            <button onClick={() => setLang('pt-BR')}>Set lang to pt-BR<button>
        </div>
    );
}

Try Use Navigator Lang

Using the I18n component:

    <I18n tryUseNavigatorLang />

Note: You can use the tryUseNavigatorLang property together with the initialization.

Using the useI18n hook:

import { useI18n } from '@seudev/x-i18n';

export default props => {
    const { tryUseNavigatorLang } = useI18n();

    return (
        <div>
            <button onClick={() => tryUseNavigatorLang()}>Try use the navigator lang<button>
        </div>
    );
}

Message

import { Message } from '@seudev/x-i18n';

Props

| Name | Type | Default | Description | | -------- | ------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------- | | id | string or string[] | | The id of a message (Defined in some message file). If pass an array will be used the first found message. | | params | object | | An object with param, to interpolate the message template. | | rawHtml | boolean | false | Use true to enable support to Html tags in the message. | | default | string | | The message returned if not found a message with the given id. | | as | string or elementType | | The element type that the message will wrapped. Example: "div" or MyElement. |

• Where you desire internationalize some message:

import { Message } from '@seudev/x-i18n';

export default props => (
    <div>
        <h1><Message id="foo.bar" /><h1>
    </div>
)

• Alternatively you can use the getMessage(id, params = {}, defaultMessage):

import { useI18n } from '@seudev/x-i18n';

export default props => {
    const { getMessage } = useI18n();

    const message = getMessage('foo.bar');
    return (
        <div>
            <h1>{message}<h1>
        </div>
    );
}

See more usage examples here.

Licensing

seudev/x-i18n is provided and distributed under the Apache Software License 2.0.

Refer to LICENSE for more information.