# translation-manager-react

> An React wrapper of translationManager

Latest version **1.3.1** (published 2020-04-22) · MIT license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install translation-manager-react
pnpm add translation-manager-react
yarn add translation-manager-react
bun add translation-manager-react
```

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 1.3.1 |
| Published | 2020-04-22 |
| First published | 2020-03-04 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Node | >=8 |
| Dependencies | 2 |
| Unpacked size | 798.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | Eden Cadagiani |
| Maintainers | ecadagiani |
| Keywords | translation, manager, management, translations, i18n, json, simple, language, lang, locale, mulitlangual, internationalization, react, react-component |

## Links

- npm: https://www.npmjs.com/package/translation-manager-react
- Repository: https://github.com/ecadagiani/translationManager-react
- Homepage: https://github.com/ecadagiani/translationManager-react#readme
- Issues: https://github.com/ecadagiani/translationManager-react/issues
- npm.io page: https://npm.io/package/translation-manager-react

## Dependencies (2)

- [html-react-parser](https://npm.io/package/html-react-parser.md) ^0.10.3
- [@ecadagiani/reacttools](https://npm.io/package/@ecadagiani/reacttools.md) ^1.0.9

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 1.3.1 (latest) — 2020-04-22
- 1.3.0 — 2020-04-22
- 1.2.1 — 2020-03-09
- 1.2.0 — 2020-03-06
- 1.1.2 — 2020-03-05
- 1.1.1 — 2020-03-05
- 1.1.0 — 2020-03-04
- 1.0.4 — 2020-03-04
- 1.0.3 — 2020-03-04
- 1.0.2 — 2020-03-04
- 1.0.1 — 2020-03-04

## README

# translationManager-react
An React wrapper of [translationManager](https://github.com/ecadagiani/translationManager)

[demo](https://codesandbox.io/s/demotranslationmanagerreact-yro9g)

## Setup:
0. `npm i translation-manager && npm i translation-manager-react`

1. Create a folder `/translations` in your project (or copy [translationsExample](./example/src/translations) from this repo)

2. Under this `/translations` folder create this tree:
    - `/translations`
        - `/languages`
            - `/english`
                - `codes.json`
                - ...any other json file
            - `/french`
                - `codes.json`
                - ...any other json file
            - ...any other language

    2.1 The files `codes.json` contains all the language codes used to target this language,
    example for english `["en","EN","en-us","en-US"]`

    2.2 Next to the `codes.json` file you can create any other json file (with the name you want),
    these files will contain the translations:
    example:
     ```json
    {
        "ADD": {
            "value": "add"
        },
        "CATEGORY": {
            "value": "category",
            "plural": "categories"
        },
        "<textCode>": {
            "value": "text",
            "<special>": "textSpecial"
        }
    }
    ```
    - you have an json-schema [here](./translationsExample/languageSchema.json)

    - \<special\>: is any variant of your original text (plural, interrogative, ...)

3. execute this command `build-translations <path to your translations folder>`,
to create `languageCodes.json`, `textCodes.json`, `translations.json`. These three
files are the compilation of the previous files.

4. In your project, create a file `initTranslations.js`:
    ```javascript
    const {TranslationManager} = require("translation-manager");
    const languageCodes        = require("translations/languageCodes");
    const translations         = require("translations/translations");

    TranslationManager.initData( languageCodes, translations );
    TranslationManager.setAppLanguage( "en" );
    // check Error
    if ( process.env.ENVIRONMENT !== "prod" )
        TranslationManager.verifyJson({ redundantCheck: false });
    ```
    **IMPORTANT**:
    Import `initTranslations.js` in first, in the entrance file of your app.
    So that `TranslationManager.initData` always takes place before usage of TranslationManager

5. Finish, you can use TranslationManager:
    ```javascript
   // todo
    ```

6. Add shortcuts to the commands in your `package.json` scripts
    ```json
    {
        "scripts": {
            "build-translations": "build-translations ./translations",
            "watch-translation": "watch-translations ./translations",
            "clean-translation": "clean-translations ./translations english true true"
        }
    }
    ```

## Notes
### TranslationManager.getText
`TranslationManager.getText` does not actually return a string,
it returns an instance of the TranslationText class. TranslationText is an extends of String.
But you can use it like a string, all the methods of the string class are available,
you can Jsonify, concat, split, trim...

However:
- `typeof` return "object"
- if you print it, in the console, it display all the object
- to avoid memory link, if you no longer need a text, think to do `monTexte.destroy()`

### insertValues
You can insert values in your text, translationManager use [lodash template](https://lodash.com/docs/4.17.15#template).
In your text in json file, add `${<keyName>}`.
When you make `getText`, specify insertValue option, example:
```json
{
    "AN_ERROR_OCCURRED": {
        "value": "an error occurred: ${errorMessage}"
    }
}
```

```javascript
const err = new Error("foobar");
TranslationManager.getText(textCode.AN_ERROR_OCCURRED, {insertValues: {errorMessage: err.message}});
```

### html
You can use html tag in your text. If you use Text component, and set the props `html` to true.
An parser will convert your string in react node.

### render
To change languages dynamically, the components that own the text must be re-render,
for this, you can simply subscribe your component to `TranslatioNmanager.onLanguageUpdate()`.
But you can, more simply, use the Text component, or the hooks of this API.


## API
### [component] Text
###### props:
```javascript
Text.propTypes = {
    className:     PropTypes.string,
    textCode:      PropTypes.string, // the wanted textCode, you can find them by import the builded file: "textCodes.json"
    language:      PropTypes.string, // to force the language
    insertValues:  PropTypes.object, // an object to insert values in your text
    option:        PropTypes.oneOf( ["capitalize","capitalizeWord","capitalizeSentence","uppercase","lowercase"]), // to transform your text
    special:       PropTypes.string, // if you want a special translation example: "plural", "interogation", ...
    ExtraContent:  PropTypes.oneOfType([PropTypes.function, PropTypes.element, PropTypes.string, PropTypes.number]), // a component which will be rendered after the text
    plural:        PropTypes.bool, // to override the props special and set this to "plural"
    interrogation: PropTypes.bool, // to override the props special and set this to "interrogation"
    html:         PropTypes.bool, // if the text must be parsed

    capitalize:         PropTypes.bool, // quick props to override props option
    capitalizeWord:     PropTypes.bool, // quick props to override props option
    capitalizeSentence: PropTypes.bool, // quick props to override props option
    uppercase:          PropTypes.bool, // quick props to override props option
    lowercase:          PropTypes.bool, // quick props to override props option
};
```
###### properties:
```javascript
   Text.options = ["capitalize","capitalizeWord","capitalizeSentence","uppercase","lowercase"]
```
###### example:
```javascript
import React from "react";
import { Text } from "translation-manager-react";
import textCodes from "./translations/textCodes";

const DynamicNiceText = () => {
    return (
        <div>
            <Text textCode={textCodes.CATEGORY}/>
        </div>
    );
};
```
###### Notes
The Text Component wrap your text in a span, and add an `data-textcode` to this element.
To simplify your debugging, and when you add a new language


### [hooks] useTranslationManager
An hooks for use TranslationManager. This hooks subscribe your component to the language update event.
###### example:
```javascript
import React from "react";
import { useTranslationManager } from "translation-manager-react";
import textCodes from "./translations/textCodes";

const WithHooksTranslationManager = () => {
    const TranslationManager = useTranslationManager();
    return (
        <div>
            {TranslationManager.getText( textCodes.CATEGORY )}
        </div>
    );
};
```


### [hooks] useTextCode
This hook allows you to recover the text directly. It is the lightest solution,
and avoid too many re-render when the language change.
###### params:
- textCode: [String] the wanted textCode
- options: [Object]
    - options.special: ["value"] {string} the special value from the textCode to use
    - options.option: {string} an constant string (TranslationManager.textOptions=[capitalize,capitalizeWord,capitalizeSentence,uppercase,lowercase])
    - options.language: [appLanguage] {string} to force language
    - options.insertValues: {Object} an object of insert value {key: value}, in the translation text, you have to add ${<key>}
- forceString: [bool] (default true) if you want an TranslationText or an string,
keep true if you want't a light solution
###### example:
```javascript
import React from "react";
import { useTextCode } from "translation-manager-react";
import textCodes from "./translations/textCodes";

const WithHooksTextCode = () => {
    const textCode = textCodes.CATEGORY;
    const options = {special: "plural"};
    const forceString = true;
    const text = useTextCode( textCode, options, forceString );
    return (
        <div>
            {text}
        </div>
    );
};
```



## Commands
### build-translations
To build the translations files: `languageCodes.json`, `textCodes.json`, `translations.json`
```bash
$ build-translations <path_to_your_translations_folder>
```

### clean-translations
To clean your translations files (rearrange textCodes, sort them alphabetically and can transform their case)
```bash
$ clean-translations <path_to_your_translations_folder> <base_folder_name> <organizeOtherLanguageLikeBase> <minimizeValueCase>
```
- path_to_your_translations_folder: path to the translation folder
- base_folder_name: the name of the language folder on which all cleaning will be based.
textCodes of other languages will be stored in the same way as the selected language. Default is "english"
- organizeOtherLanguageLikeBase: if you want to store textCode in the same way as the base language.
- minimizeValueCase: if you want to transform all value in lowerCase
```bash
example:
$ clean-translations ./translations english true true
```

### watch-translations
To watch the change in folder translations, with this command effective,
any changement in translations files, trigger build-translations
```bash
$ watch-translations <path_to_your_translations_folder>
```


### TranslationManager API
[here](https://github.com/ecadagiani/translationManager/blob/master/README.md)



## Authors
- **Eden Cadagiani** for [HelloMyBot](https://hellomybot.io/fr/bienvenue/)



## License
This project is licensed under the MIT - see the [LICENSE](LICENSE) file for details

---
_Source: https://npm.io/package/translation-manager-react · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._