App Translator

Define multiple dictionaries for your app and translate strings instantly at runtime.
This tool does not call external APIs to translate your strings, you must first define yours dictionaries.

Installation

npm install app-translator

Compatibility

Compatible with Node >=8.0.0

Features

Easy to use
You can add languages with just putting the dictionary in your lang folder
Can infer the browser language and search if a related dictionary is defined
Do not need to reload the app to switch the language
Extremely small

Other features

Static type checking with typescript declaration files
Exhaustive doc comments
Tree shakable: exported with ESM modules
Tested with available coverage report

API

Index

Dictionary
Collection
AppTranslatorOptions
initTranslator
translate (alias t)
tryUseBrowserLanguage
getAvailableLanguages
setLanguage
setOptions

Dictionary

Interface

Define a single dictionary.

Property	Type	Description
name	string	The language name
bcp47	string	A valid BCP47 tag
pairs	{ [ original: string ]: string }	Pairs of original-translated strings

Collection

interface

Define the dictionaries collection in an array of dictionaries.

Array <Dictionary>

AppTranslatorOptions

Interface

Define options for AppTranslator.

Property	Type	Description
caseSensitive?	boolean	Look for the string in dictionary without consider the letters case
autoCapitalize?	boolean	Capitalize automatically the first letter
logs?	boolean	Emit warns and non-blocking errors to the console

initTranslator

Function ( language: string, collection?: Collection, options?: AppTranslatorOptions ): void

Initialize App Translator with a target language, a collection and custom options. If a collection is not provided, translate() method will bypass your strings.
⚠ It throws an error if you try to initialize App Translator multiple times.

Parameter	Type	Description
language	string	The primary dictionary to use for translations
collection?	Collection	The collection of dictionaries
options?	AppTranslatorOptions	Define the behavior of AppTranslator

translate (alias t)

Function ( originalStr: string | number, capitalize?: boolean ): string

Return the translated string in the chosen language or the original string if no translation was found

Parameter	Type	Description
originalStr	string or number	The original string in the code
capitalize	boolean	Capitalize the first letter of the output

tryUseBrowserLanguage

Function(): string | null

Try to infer the dictionary from the browser. It compares the bcp47 tag in the dictionaries with navigator.language. If a dictionary was found, it returns the found language name and sets it as primary language. Otherwise returns null and does not change the language.

getAvailableLanguages

Function(): Array<string>

Return an array of the names of the currently loaded dictionaries.

setLanguage

Function(language: string): void

Set a new primary language. If not present in the collection will generate a console error but will not change the language.

setOptions

Function(options: AppTranslatorOptions): void

Override the provided new options with the old one.
⚠ It throws an error if you pass invalid options

Examples

You can import dictionaries as json or js modules. In this example I'll use the ES js modules.

Put your dictionaries in src/languages/

export const italian = {
    name: 'italian',
    bcp47: 'it-IT',
    pairs: {
        'leave a comment': 'lascia un commento',
    },
}

Define an index in src/languages/ with all your exported languages (you can skip this step and import directly in your entry point, but this is more pratical for many dictionaries)

export * from './russian'
export * from './german'
export * from './italian'
export * from './spanish'

Import them grupped and create your collection

import * as languages from './languages'
const collection = Object.values(languages)

Initialize App Translator

import { initTranslator } from "app-translator";
initTranslator("italian", collection, { caseSensitive: false, autoCapitalize: true });

Now the dictionaries and options are available in window.appTranslator.

Translate everywhere! (Example in React)

import { t } from "app-translator";

const App = () => {
  return <h1>{ t("leave a Comment") }</h1>;
};

Folder structure:
src/
--main.js
--languages/
----russian.js
----german.js
----italian.js
----spanish.js
----index.js

You can use App Translator even without a module system or organize your exports as you think is best, there are no specific rules about it.

Dependencies

No dependencies

License

MIT

jonamat / app-translator