README.md

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.