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
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
Define the dictionaries collection in an array of dictionaries.
Array <Dictionary>
AppTranslatorOptions
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
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
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.
Links
Dependencies
No dependencies
License
MIT