Skip to content

Commit

Permalink
Merge pull request #111 from GertjanReynaert/gr-upgrade-dependencies
Browse files Browse the repository at this point in the history 
Upgrade dependencies
  • Loading branch information
@GertjanReynaert
GertjanReynaert authored Mar 29, 2018
2 parents acc89f7 + 3245b24 commit 8ff03af
Show file tree
Hide file tree
Showing 4 changed files with 1,909 additions and 864 deletions.
208 changes: 123 additions & 85 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -38,26 +38,30 @@ now you know what messages you still need to update.
yarn add --dev react-intl-translations-manager
```

or
or

```
npm i --save-dev react-intl-translations-manager
```

## Setup

### Basic

This is an example of the most basic usage of this plugin, in the API documentation below you can find more options.

Create a script in your package.json

```json
{
"scripts": {
"manage:translations": "node ./translationRunner.js"
}
}
```

Create a file with your config you can run with the npm script

```js
// translationRunner.js
const manageTranslations = require('react-intl-translations-manager').default;
Expand All @@ -68,7 +72,7 @@ const manageTranslations = require('react-intl-translations-manager').default;
manageTranslations({
messagesDirectory: 'src/translations/extractedMessages',
translationsDirectory: 'src/translations/locales/',
languages: ['nl'], // any language you need
languages: ['nl'] // any language you need
});
```

Expand Down Expand Up @@ -103,64 +107,74 @@ these messages.

#### Config

- `messagesDirectory` (required),
- Directory where the babel plugin puts the extracted messages. This path is
relative to your projects root.
- example: `src/locales/extractedMessages`
- `translationsDirectory` (required),
- Directory of the translation files the translation manager needs to maintain.
- example: `src/locales/lang`
- `whitelistsDirectory` (optional, default: `translationsDirectory`)
- Directory of the whitelist files the translation manager needs to maintain.
These files contain the key of translations that have the exact same text in
a specific language as the defaultMessage. Specifying this key will suppress
`unmaintained translation` warnings.
- example: `Dashboard` in english is also accepted as a valid translation for
dutch.
- `languages` (optional, default: `[]`)
- What languages the translation manager needs to maintain. Specifying no
languages actually doesn't make sense, but won't break the translationManager
either. (Please do not include the default language, react-intl will automatically include it.)
- example: for `['nl', 'fr']` the translation manager will maintain a
`nl.json`, `fr.json`, `whitelist_nl.json` and a `whitelist_fr.json` file
- `singleMessagesFile` (optional, default: `false`)
- Option to output a single JSON file containing the aggregate of all extracted messages,
grouped by the file they were extracted from.
- example:
* `messagesDirectory` (required),
* Directory where the babel plugin puts the extracted messages. This path is
relative to your projects root.
* example: `src/locales/extractedMessages`
* `translationsDirectory` (required),
* Directory of the translation files the translation manager needs to maintain.
* example: `src/locales/lang`
* `whitelistsDirectory` (optional, default: `translationsDirectory`)
* Directory of the whitelist files the translation manager needs to maintain.
These files contain the key of translations that have the exact same text in
a specific language as the defaultMessage. Specifying this key will suppress
`unmaintained translation` warnings.
* example: `Dashboard` in english is also accepted as a valid translation for
dutch.
* `languages` (optional, default: `[]`)
* What languages the translation manager needs to maintain. Specifying no
languages actually doesn't make sense, but won't break the translationManager
either. (Please do not include the default language, react-intl will automatically include it.)
* example: for `['nl', 'fr']` the translation manager will maintain a
`nl.json`, `fr.json`, `whitelist_nl.json` and a `whitelist_fr.json` file
* `singleMessagesFile` (optional, default: `false`)
* Option to output a single JSON file containing the aggregate of all extracted messages,
grouped by the file they were extracted from.
* example:
```json
[
{
"path": "src/components/foo.json",
"descriptors": [
{
"id": "bar",
"description": "Text for bar",
"defaultMessage": "Bar",
}
]
}
]
[
{
"path": "src/components/foo.json",
"descriptors": [
{
"id": "bar",
"description": "Text for bar",
"defaultMessage": "Bar"
}
]
}
]
```
- `detectDuplicateIds` (optional, default: `true`)
- If you want the translationManager to log duplicate message ids or not
- `sortKeys` (optional, default: `true`)
- If you want the translationManager to sort it's output, both json and console output
- `jsonOptions` (optional, default: { space: 2, trailingNewline: false })
- `overridePrinters` (optional, default: {})
- Here you can specify custom logging methods. If not specified a default printer is used.
- Possible printers to configure:
* `detectDuplicateIds` (optional, default: `true`)
* If you want the translationManager to log duplicate message ids or not
* `sortKeys` (optional, default: `true`)
* If you want the translationManager to sort it's output, both json and console output
* `jsonOptions` (optional, default: { space: 2, trailingNewline: false })
* `overridePrinters` (optional, default: {})
* Here you can specify custom logging methods. If not specified a default printer is used.
* Possible printers to configure:
```js
const printers = {
printDuplicateIds: ( duplicateIds ) => { console.log(`You have ${duplicateIds.length } duplicate IDs`) },
printLanguageReport: ( report ) => { console.log('Log report for a language') },
printNoLanguageFile: ( lang ) => { console.log(`No existing ${lang} translation file found. A new one is created.`) },
printNoLanguageWhitelistFile: ( lang ) => { console.log(`No existing ${lang} file found. A new one is created.`) },
};
const printers = {
printDuplicateIds: duplicateIds => {
console.log(`You have ${duplicateIds.length} duplicate IDs`);
},
printLanguageReport: report => {
console.log('Log report for a language');
},
printNoLanguageFile: lang => {
console.log(
`No existing ${lang} translation file found. A new one is created.`
);
},
printNoLanguageWhitelistFile: lang => {
console.log(`No existing ${lang} file found. A new one is created.`);
}
};
```
- `overrideCoreMethods` (optional, default: {})
- Here you can specify overrides for the core hooks. If not specified, the
default methods will be used.
- Possible overrides to configure:
* `overrideCoreMethods` (optional, default: {})
* Here you can specify overrides for the core hooks. If not specified, the
default methods will be used.
* Possible overrides to configure:
```js
const overrideCoreMethods = {
provideExtractedMessages: () => {},
Expand All @@ -171,8 +185,8 @@ these messages.
provideTranslationsFile: () => {},
provideWhitelistFile: () => {},
reportLanguage: () => {},
afterReporting: () => {},
}
afterReporting: () => {}
};
```

#### Fully configured
Expand All @@ -192,13 +206,23 @@ manageTranslations({
sortKeys: false,
jsonOptions: {
space: 4,
trailingNewline: true,
trailingNewline: true
},
overridePrinters: {
printDuplicateIds: ( duplicateIds ) => { console.log(`You have ${duplicateIds.length } duplicate IDs`) },
printLanguageReport: ( report ) => { console.log('Log report for a language') },
printNoLanguageFile: ( lang ) => { console.log(`No existing ${lang} translation file found. A new one is created.`) },
printNoLanguageWhitelistFile: ( lang ) => { console.log(`No existing ${lang} file found. A new one is created.`) },
printDuplicateIds: duplicateIds => {
console.log(`You have ${duplicateIds.length} duplicate IDs`);
},
printLanguageReport: report => {
console.log('Log report for a language');
},
printNoLanguageFile: lang => {
console.log(
`No existing ${lang} translation file found. A new one is created.`
);
},
printNoLanguageWhitelistFile: lang => {
console.log(`No existing ${lang} file found. A new one is created.`);
}
},
overrideCoreMethods: {
provideExtractedMessages: () => {},
Expand All @@ -209,12 +233,12 @@ manageTranslations({
provideTranslationsFile: () => {},
provideWhitelistFile: () => {},
reportLanguage: () => {},
afterReporting: () => {},
},
afterReporting: () => {}
}
});
```

*This config is only as illustration for all possible options, these arent
\*This config is only as illustration for all possible options, these arent
recommended configuration options.

### CoreMethods
Expand All @@ -223,48 +247,54 @@ These are the core methods of the translationManager and what purpose they
serve.

#### provideExtractedMessages

```js
const extractedMessages = provideExtractedMessages();
```

Here you should return all extracted messages. This should be an array, with an object per file. Each object should at least contain a `descriptors` key which in turn has an array of message objects. Each message object should at least contain the id and message.
Example:

```js
// Minimal expected return value
const extractedMessages = [
{
descriptors: [
{
id: 'foo_ok',
defaultMessage: 'OK',
},
],
},
defaultMessage: 'OK'
}
]
}
];
```

#### outputSingleFile

```js
outputSingleFile(extractedMessages);
```

This gives you the option to output the extractedMessages. This way you can for example shrink all extracted files into a single File containing all messages.

#### outputDuplicateKeys

```js
outputDuplicateKeys(duplicateIds);
```

This gives you the option to warn for duplicate ids.

#### beforeReporting

```js
beforeReporting();
```

Here you can do the preparation of the reporting, like creating the necessary folders, or printing a start message

#### provideLangTemplate

```js
const languageResults = provideLangTemplate(lang);
```
Expand All @@ -273,51 +303,57 @@ Here you should provide the template for the language results. This is just a ba
The following keys are restricted and will be overridden by the core: `report`, `noTranslationFile` and `noWhitelistFile`.

#### provideTranslationsFile

```js
const translationsFile = provideTranslationsFile(languageResults);
```

Here you should return the translations for the specified language. This must be an object with the message id and message in a key value format.

```js
const translationsFile = {
messageId: 'message',
messageId: 'message'
};
```

#### provideWhitelistFile

```js
const whitelistFile = provideWhitelistFile(languageResults);
```

Here you should return the whitelisted messsage ids for the specified language. This must be an array of strings.

```js
const whitelistFile = [
'messageId',
];
const whitelistFile = ['messageId'];
```

#### reportLanguage

```js
reportLanguage(languageResults)
reportLanguage(languageResults);
```

Here you can handle the reporting of the results for a language, like logging and creating files based on the results.

#### afterReporting

```js
afterReporting()
afterReporting();
```

Here you can do actions after all reports are made, like cleanup or printing a finished message.

### readMessageFiles

```js
const extractedMessages = readMessageFiles(messagesDirectory);
```

This is a `babel-plugin-react-intl` specific helper method. It will read all extracted JSON file for the specified directory, filter out all files without any messages, and output an array with all messages.

Example output:

```js
const extractedMessages = [
{
Expand All @@ -326,26 +362,28 @@ const extractedMessages = [
{
id: 'foo_ok',
description: 'Ok text',
defaultMessage: 'OK',
},
],
},
defaultMessage: 'OK'
}
]
}
];
```

### createSingleMessagesFile

```js
createSingleMessagesFile({ messages, directory });
```

This helper method will output all messages (potentially read by `readMessageFiles`) in a single jsonFile.

- messages: (required)
- directory: (required, string) contains the path to the directory where the file should be written into.
- fileName: (optional, default: `defaultMessages.json`) this filename should contain the `.json` extension
- jsonSpaceIndentation: (optional, default: `2`) number of spaces used for indentation (0-10)
* messages: (required)
* directory: (required, string) contains the path to the directory where the file should be written into.
* fileName: (optional, default: `defaultMessages.json`) this filename should contain the `.json` extension
* jsonSpaceIndentation: (optional, default: `2`) number of spaces used for indentation (0-10)

### getDefaultMessages

```js
const messages = getDefaultMessages(extractedMessages);
```
Expand All @@ -355,7 +393,7 @@ This helper method will flatten all files (as returned from `readMessageFiles`)
```js
const messages = {
messages: {
messageId: 'message',
messageId: 'message'
},
duplicateIds: [
// potentially double used message keys,
Expand Down
Loading

0 comments on commit 8ff03af

Please sign in to comment.