Manage localization with static analysis.
Installation
npm install --save-dev i18n-extract
The problem solved
This module analyses code statically for key usages, such as i18n.t('some.key')
, in order to:
- Report keys that are missing
- Report keys that are unused.
- Report keys that are highly duplicated.
E.g. This module works well in conjunction with:
Supported keys
i18n('key.static')
i18n('key.' + 'concat')
i18n(`key.template`)
i18n(`key.${dynamic}`)
API
Parse the code
to extract the argument of calls of i18n(key
).
code
should be a string.- Return an array containing keys used.
Example
import {extractFromCode} from 'i18n-extract';
const keys = extractFromCode("const followMe = i18n('b2b.follow');", {
marker: 'i18n',
});
Parse the files
to extract the argument of calls of i18n(key
).
files
can be either an array of strings or a string. You can also use a glob.- Return an array containing keys used in the source code.
Example
import {extractFromFiles} from 'i18n-extract';
const keys = extractFromFiles([
'*.jsx',
'*.js',
], {
marker: 'i18n',
});
Options
marker
: The name of the internationalized string marker function. Defaults to i18n
.keyLoc
: An integer indicating the position of the key in the arguments. Defaults to 0
. Negative numbers, e.g., -1
, indicate a position relative to the end of the argument list.parser
: Enum indicate the parser to use, can be typescript
or flow
. Defaults to flow
.babelOptions
: A Babel configuration object to allow applying custom transformations or plugins before scanning for i18n keys. Defaults to a config with all babylon plugins enabled.
findMissing(locale, keysUsed)
Report the missing keys. Those keys should probably be translated.
locale
should be a object containing the translations.keysUsed
should be an array. Containes the keys used in the source code.
It can be retrieve with extractFromFiles
our extractFromCode
.- Return a report.
Example
import {findMissing} from 'i18n-extract';
const missing = findMissing({
key1: 'key 1',
}, ['key1', 'key2']);
Plugins
findUnused(locale, keysUsed)
Report the unused key. Those keys should probably be removed.
locale
should be a object containing the translations.keysUsed
should be an array. Containes the keys used in the source code.
It can be retrieve with extractFromFiles
our extractFromCode
.- Return a report.
Example
import {findUnused} from 'i18n-extract';
const unused = findUnused({
key1: 'key 1',
key2: 'key 2',
}, ['key1']);
findDuplicated(locale, keysUsed, options)
Report the duplicated key. Those keys should probably be mutualized.
The default threshold
is 1, it will report any duplicated translations.
locale
should be a object containing the translations.keysUsed
should be an array. Containes the keys used in the source code.
It can be retrieve with extractFromFiles
our extractFromCode
.options
should be an object. You can provide a threshold
property to change the number of duplicated value before it's added to the report.- Return a report.
Example
import {findDuplicated} from 'i18n-extract';
const duplicated = findDuplicated({
key1: 'Key 1',
key2: 'Key 2',
key3: 'Key 2',
});
forbidDynamic(locale, keysUsed)
Report any dynamic key. It's arguably more dangerous to use dynamic key. They may break.
locale
should be a object containing the translations.keysUsed
should be an array. Containes the keys used in the source code.
It can be retrieve with extractFromFiles
our extractFromCode
.- Return a report.
Example
import {forbidDynamic} from 'i18n-extract';
const forbidDynamic = forbidDynamic({}, ['key.*']);
flatten(object)
Flatten the object.
object
should be a object.
Example
import {flatten} from 'i18n-extract';
const flattened = flatten({
key2: 'Key 2',
key4: {
key41: 'Key 4.1',
key42: {
key421: 'Key 4.2.1',
},
},
});
mergeMessagesWithPO(messages, poInput, poOutput)
Output a new po file with only the messages present in messages
.
If a message is already present in the poInput
, we keep the translation.
If a message is not present, we add a new empty translation.
messages
should be an array.poInput
should be a string.poOutput
should be a string.
Example
import {mergeMessagesWithPO} from 'i18n-extract';
const messages = ['Message 1', 'Message 2'];
mergeMessagesWithPO(messages, 'messages.po', 'messages.output.po');
License
MIT