Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

babel-plugin-i18next-extract

Package Overview
Dependencies
Maintainers
1
Versions
37
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

babel-plugin-i18next-extract

Statically extract translation keys from i18next application.

  • 0.1.0-alpha.2
  • Source
  • npm
  • Socket score

Version published
Weekly downloads
42K
decreased by-11.76%
Maintainers
1
Weekly downloads
 
Created
Source

babel-plugin-i18next-extract

License: MIT Build Status codecov PRs Welcome Greenkeeper badge NPM


Note: This project is still under active, early development.

babel-plugin-i18next-extract is a Babel Plugin that will traverse your JavaScript/Typescript code in order to find i18next translation keys.

Installation

yarn add --dev babel-plugin-i18next-extract

# or

npm i --save-dev babel-plugin-i18next-extract

Usage

If you already use Babel, chances are you already have an babel configuration (e.g. a .babelrc file). Just add declare the plugin and you're good to go:

{
  "plugins": [
    "i18next-extract",
    // your other plugins…
  ]
}

You can also specify additional configuration options to the plugin:

{
  "plugins": [
    ["i18next-extract", {"nsSeparator": "~"}],
    // your other plugins…
  ]
}

Once you are set up, you can build your app normally or run Babel through Babel CLI:

yarn run babel -f .babelrc 'src/**/*.{js,jsx,ts,tsx}'

# or

npm run babel -f .babelrc 'src/**/*.{js,jsx,ts,tsx}'

Extracted translations should land in the extractedTranslations/ directory. Magic huh?

If you don't have a babel configuration yet, you can follow the Configure Babel documentation to try setting it up.

Usage with create-react-app

create-react-app doesn't let you modify the babel configuration. Fortunately, it's still possible to use this plugin without ejecting. First of all, install Babel CLI:

yarn add --dev @babel/cli

# or

npm add --save-dev @babel/cli

Create a minimal .babelrc that uses the react-app babel preset (DO NOT install it, it's already shipped with CRA):

{
  "presets": ["react-app"],
  "plugins": ["i18next-extract"]
}

You should then be able to extract your translations using the CLI:

# NODE_ENV must be specified for react-app preset to work properly
NODE_ENV=development yarn run babel -f .babelrc 'src/**/*.{js,jsx,ts,tsx}'

To simplify the extraction, you can add a script to your package.json:

"scripts": {
  […]
  "i18n-extract": "NODE_ENV=development babel -f .babelrc 'src/**/*.{js,jsx,ts,tsx}'",
  […]
}

And then just run:

yarn run i18n-extract

# or

npm run i18n-extract

Features

  • Translation extraction in JSON v3 format.
  • Detection of i18next.t() function calls.
  • Plural forms support:
    • Keys derivation depending on the locale.
    • Automatic detection from i18next.t function calls.
    • Automatic detection from react-i18next properties.
    • Manual detection from comment hints.
  • Contexts support:
    • Naïve implementation with default contexts.
    • Automatic detection from i18next.t function calls.
    • Automatic detection from react-i18next properties.
    • Manual detection from comment hints.
  • react-i18next support:
    • Trans component support (with plural forms, contexts and namespaces).
    • useTranslation hook support (with plural forms, contexts and namespaces).
    • Translation render prop support (with plural forms, contexts and namespaces).
    • (todo) Fuzzy namespace inference from withTranslation HoC.
  • Namespace inference:
    • Depending on the key value.
    • Depending on the t() function options.
    • Depending on the ns property in Translation render prop.
    • Depending on the ns attribute in the Trans component.
  • Explicitely disable extraction on a specific file sections or lines using comment hints.
  • … and more?

Configuration

OptionTypeDescriptionDefault
localesstring[]All the locales your project supports. babel-plugin-i18next-extract will generate a JSON file for each locale.['en']
defaultNSstringThe default namespace that your translation use.'translation'
pluralSeparatorstringString you want to use to split plural from keys. See i18next Configuration options'_'
contextSeparatorstringString you want to use to split context from keys. See i18next Configuration options'_'
keySeparatorstring or nullString you want to use to split keys. Set to null if you don't want to split your keys or if you want to use keys as value. See i18next Configuration options'.'
nsSeparatorstring or nullString you want to use to split namespace from keys. Set to null if you don't want to infer a namespace from key value or if you want to use keys as value. See See i18next Configuration options':'
i18nextInstancesNamesstring[]Possible names of you i18next object instances. This will be used to detect i18next.t calls.['i18next', 'i18n']
defaultContextsstring[]Default context keys to create when detecting a translation with context.['', '_male', '_female']
outputPathstringPath where translation keys should be extracted to. You can put {{ns}} and {{locale}} placeholders in the value to change the location depending on the namespace or the locale.extractedTranslations/{{locale}}/{{ns}}.json
defaultValuestring or nullDefault value for extracted keys.'' (empty string)
keyAsDefaultValueboolean or string[]If true, use the extracted key as defaultValue (ignoring defaultValue option). You can also specify an array of locales to apply this behavior only to a specific set locales (e.g. if you keys are in plain english, you may want to set this option to ['en']).false
keyAsDefaultValueForDerivedKeysbooleanIf false and keyAsDefaultValue is enabled, don't use derived keys (plural forms or contexts) as default value. defaultValue will be used instead.true
exporterJsonSpacenumberNumber of indentation space to use in extracted JSON files.2

Comment hints

Disable extraction on a specific section

If the plugin extracts a key you want to skip or erroneously tries to parse a function that doesn't belong to i18next, you can use a comment hint to disable the extraction:

// i18next-extract-disable-next-line
i18next.t("this key won't be extracted")

i18next.t("neither this one") // i18next-extract-disable-line

// i18next-extract-disable
i18next.t("or this one")
i18next.t("and this one")
// i18next-extract-enable

i18next.t("but this one will be")

You can put a // i18next-extract-disable comment at the top of the file in order to disable extraction on the entire file.

Explicitly specify contexts for a key

This is very useful if you want to use different contexts than the default male and female for a given key:

// i18next-extract-mark-context-next-line ["dog", "cat"]
i18next.t("this key will have dog and cat context", {context: dogOrCat})

// i18next-extract-mark-context-next-line
i18next.t("this key will have default context, although no context is specified")

// i18next-extract-mark-context-next-line disable
i18next.t("this key wont have a context, although a context is specified", {context})

i18next.t("can be used on line") // i18next-extract-mark-context-line

// i18next-extract-mark-context-start
i18next.t("or on sections") 
// i18next-extract-mark-context-stop

const transComponent = (
  // i18next-extract-mark-context-next-line
  <Trans>it also works on Trans components</Trans>
)

Explicitly use a namespace for a key

// i18next-extract-mark-ns-next-line forced-ns
i18next.t("this key will be in forced-ns namespace")

i18next.t("this one also", {ns: 'this-ns-wont-be-used'}) // i18next-extract-mark-ns-line forced-ns

// i18next-extract-mark-ns-start forced-ns
i18next.t("and still this one")
// i18next-extract-mark-ns-stop forced-ns

Explicitly enable/disable a plural form for a key

// i18next-extract-mark-plural-next-line
i18next.t("this key will be in forced in plural form")

// i18next-extract-mark-plural-next-line disable
i18next.t("this key wont have plural form", {count})

Gotchas

The plugin tries to be smart, but can't do magic. i18next has a runtime unlike this plugin which must guess everything statically. For instance, you may want to disable extraction on dynamic keys:

i18next.t(myVariable);
i18next.t(`error.${code}`);

If you try to extract keys from this code, the plugin will issue a warning because it won't be able to infer the translations statically. If you really want to specify variable keys, you should skip them with a comment hint. The same goes for plural forms, context and namespace detection:

i18next.t("myKey", myOpts); // This won't work.

However, in React components, it might come handy to be a little smarter than that. That's why when using a <Trans> component, the plugin will try to resolve references before resigning. For instance, this code should extract properly:

const foo = <p>Hello</p>
const bar = <Trans>{foo} world</Trans>

Keywords

FAQs

Package last updated on 26 Jun 2019

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc