k2-react-translate

A simple, easy-to-use translation library based on React's Context API, with optional localized react-router routing.

See demo on CodeSandbox.

Table of Contents

• Problem Statement
• Setup
• Documentation (Translation)
• Documentation (Localized Routing)
• Development
• Known Issues
• Changelog

Problem Statement

TBD

Setup

This ES5 module is distributed via npm and should be installed as a production dependency.

Note: TypeScript syntax is used throughout the docs, but the library should run without issue on a babel/react setup.

Using yarn (preferred)

yarn add -E k2-react-translate

or via npm

npm i -S -E k2-react-translate

peerDependencies

• react@^16.8.0
  • react@^16.8.0 would have to be installed to use the useTranslate hook.
• react-dom@^16.8.0
• react-router-dom
• history

Typescirpt type definitions come bundled in.

Project Setup

If using TypeScript in VS Code, add the following configuration to your tsconfig.json to allow for importing json files into your modules:

// tsconfig.json
{
	"compilerOptions": {
		// other config options ...
		"resolveJsonModule": true
	}
}

Setup your translations:

If using VS Code, the richie5um2's Sort JSON objects marketplace extension may help to keep your translations file organized.

// translations.json
{
	"HELLO": {
		"en": "Hello",
		"fr": "Bonjour"
	},
	"HELLO_NAME": {
		"en": "Hello, {firstName}",
		"fr": "Bonjour, {firstName}"
	},
	"AVAILABLE_IN_COUNTRY": {
		"en": "Available in {countryName}",
		"fr": "Disponsible en {countryName}"
	},
	"PRIVACY_POLICY": {
		"en": "<a href="{link}">Privacy Policy</a>",
		"fr": "<a href="{link}">Politique de Confidentialité</a>"
	}
}

Entry point:

// index.tsx
import * as React from 'react'; // standard TypeScript syntax
import * as ReactDOM from 'react-dom'; // standard TypeScript syntax
import { LocaleProvider } from 'k2-react-translate';
import { App } from './App';
import translations from './translations.json';

ReactDOM.render(
	
		
	,
	document.getElementById('app')
);

Documentation (Translation)

k2-react-translate barrels (re-exports) the following sub-modules as named exports:

`` - source

A Context API wrapper to ``. This wrapper is required to apply k2-react-translate translations.

Usage

See Project Setup above.

useTranslate - source

A custom hook for use in Function Components.

Dependencies: react@^16.8.0, react-dom@^16.8.0

Usage

// MyComponent.tsx
import * as React from 'react'; // standard TypeScript syntax
import { useTranslate } from 'k2-react-translate';

const links = {
	en: '/en/privacy-policy',
	fr: '/fr/privacy-policy',
};

const MyComponent: React.FunctionComponent<{}> = () => {
	const { translate, translateAndParse, language, changeLanguage } = useTranslate();

	const handleClick = (): void => {
		// change language to French
		changeLanguage('fr');
	};

	return (
		<div>
			{translate('HELLO')}
			// "Hello" (en) - string // "Bonjour" (fr) - string
			{translate('HELLO_NAME', { firstName: 'Jaqen' })}
			// "Hello, Jaqen" (en) - string // "Bonjour, Jaqen" (fr) - string
			{translateAndParse('PRIVACY_POLICY', { link: links[language] })}
			// <a href="/en/privacy-policy">Privacy Policy</a> (en) - ReactElement // <a href="/fr/privacy-policy">
				Politique de Confidentialité
			</a> (fr) - ReactElement
			<button>Change Language</button>
		</div>
	);
};

`` - source

A React component that wraps `` that performs translations, given translation keys as prop arguments.

If using react v16.8.0+, I'd strongly recommend using the useTranslate hook above instead. useTranslate works in the same way but provides for cleaner and less verbose use.

Usage

// MyComponent.tsx
import * as React from 'react'; // standard TypeScript syntax
import { Translator } from 'k2-react-translate';

const links = {
	en: '/en/privacy-policy',
	fr: '/fr/privacy-policy',
};

const MyComponent: React.StatelessComponent<{}> = () => {
	return (
		<div>
			
			// "Hello" (en) - string // "Bonjour" (fr) - string
			
			// "Hello, Jaqen" (en) - string // "Bonjour, Jaqen" (fr) - string
			
			// <a href="/en/privacy-policy">Privacy Policy</a> (en) - ReactElement // <a href="/fr/privacy-policy">
				Politique de Confidentialité
			</a> (fr) - ReactElement
		</div>
	);
};

`` - source

A button wrapped React component that provides the ability to set languages.

Switching languages can alternatively be performed under an exposed function in the useTranslate hook documented here.

Usage

// MyComponent.tsx
import * as React from 'react'; // standard TypeScript syntax
import { LanguageSwitcher } from 'k2-react-translate';

const MyComponent: React.FunctionComponent<{}>=()=>{

    const handleClick:(changeLanguage: (language:string)=> void ): void=>{
        // change language to French
        changeLanguage('fr');
    }

    return <div>
        
    </div>;
}

Documentation (Localized Routing)

Localized routing is optional. If used, react-router-dom would need to be installed as a production dependency.

`` - source

Provides a simple, non-intrusive way of setting up localized routes. Returns localized s or s components given the routes prop config.

If is used, you need not wrap your RouterConfig with or as this is done within.

`` is not recursive.