mini-i18n-extract-plugin

I18n (JSON or YAML) extraction Webpack plugin based off mini-css-extract-plugin

🏠 Homepage | 🗃 Repository | 📦 NPM | 📚 Documentation | 🐛 Issue Tracker

🪑 Table of Content

• 🧰 Features
• 👶 Install
• 🚀 Usage
• 🔮 Background
• 🤖 API
• ⏳ Changelog
• 🛠 Developing
• 🏗 Roadmap
• 🤝 Contributing
• 🧙 Contributors
• ⭐ Show your support
• 🐙 Community
• 🔗 Related Projects
• 👨‍🔧 Maintainers
• 📝 License

🧰 Features

• Split i18n data by locales
• The plugin understands following formats:
  • JSON files
  • YAML files
  • vue-i18n-loader output
• Exports either JSON or YAML

👶 Install

npm install -D mini-i18n-extract-plugin

🚀 Usage

See the example in the ./example subdirectory. To build the example, run:

npm run example

Which outputs the build to ./temp/example.

Minimal setup

Say you have i18n data you want to extract. For example:

component.i18n.json

{
  "en": {
    "greeting": "hello"
  },
  "de": {
    "greeting": "tschüss"
  }
}

component.js

import './component.i18n.json';

To extract i18n files and split them by locales, add the loader and the plugin to Webpack config. For example:

webpack.config.js

const MiniI18nExtractPlugin = require('mini-i18n-extract-plugin').default;
// or
// import MiniI18nExtractPlugin from 'mini-i18n-extract-plugin';

// Plugin must be instantiated before use
const i18nExtractPlugin = new MiniI18nExtractPlugin();

module.exports = {
  plugins: [i18nExtractPlugin],
  module: {
    rules: [
      {
        test: /\.i18n\.json$/i,
        use: [i18nExtractPlugin.asLoader], // note the 'asLoader' property
      },
    ],
  },
};

By default, this will output the i18n JSON as separate files, split by locales, and named as [name].i18n.[locale].[ext], e.g. main.i18n.en.json. (See the default implementation for details).

To automatically inline the generated i18n files in HTML generated by html-webpack-plugin, use html-webpack-inline-i18n-plugin.

Inputs

The plugin can parse JSON and YAML files, and output from vue-i18n-loader.

A single instance can be used for all of them:

import MiniI18nExtractPlugin from 'mini-i18n-extract-plugin';
// or const MiniI18nExtractPlugin = require('mini-i18n-extract-plugin').default

// Plugin must be instantiated before use
const i18nExtractPlugin = new MiniI18nExtractPlugin();

module.exports = {
  plugins: [i18nExtractPlugin],
  module: {
    rules: [
      // Parse JSON files
      {
        test: /\.i18n\.json$/i,
        use: [
          i18nExtractPlugin.asLoader, // note the 'asLoader'
        ],
      },
      // Parse YAML files
      {
        test: /\.i18n\.ya?ml$/,
        type: 'json',
        use: [
          i18nExtractPlugin.asLoader, // note the 'asLoader'
          'yaml-loader',
        ],
      },
      // Parse Vue i18n blocks using vue-loader
      {
        test: /\.vue$/u,
        use: ['vue-loader'],
      },
      {
        resourceQuery: /blockType=i18n/,
        type: 'javascript/auto',
        use: [
          i18nExtractPlugin.asLoader, // note the 'asLoader'
          '@intlify/vue-i18n-loader',
        ],
      },
    ],
  },
};

Input resolution

Format of the data (JSON vs YAML) is dynamically resolved based on following rules:

1. The request string indicates the resource comes from vue-i18n-loader?

   • Specifically, the request is checked for vue and blockType=i18n query params.

   • If request contains lang=yaml query param, it's read as YAML, otherwise as JSON.

2. The request string has json or yaml / yml query params?

   • This enables you to pass files with custom extensions and have them parsed as JSON or YAML.

     // If this request will be passed to
     // MiniI18nExtractPlugin's loader, it will be read
     // as YAML
     require('my.i18n?yaml');

3. The resource has .json or .yaml / .yml extension?

If none of the rules succeed, the fallback is to interpret the resource as JSON.

Options

Options are passed to the plugin on instantiation.

const MiniI18nExtractPlugin = require('mini-i18n-extract-plugin');

const i18nExtractPlugin = new MiniI18nExtractPlugin({
  // pass them configs here
  exportType: 'yaml',
  ...
});

The plugin accepts same options the default options of mini-extract-plugin (which is based on the options of mini-css-extract-plugin v0.9.0).

In addition to that, 2 custom options are available:

exportType

• Type: 'json' | 'yaml' | undefined
• How the extracted data should be exported.
• Defaults to 'json'.

splitLocales

• Type: boolean | undefined
• Whether the extracted i18n data should be split by locales. If true, separate file is generated for each locale per each entrypoint, otherwise all extracted data is in a single file per each entrypoint.
• Defaults to true.

Typing

This project is written in TypeScript and the typings are included in the distribution.

Types used in this package can be imported and used as such:

import { types } from 'mini-i18n-extract-plugin';

const plugin: types.MiniI18nExtractPlugin = ...

Debugging

This project uses debug. To show debug logs, activate debug for mini-i18n-extract-plugin.

CLI example:

DEBUG=mini-i18n-extract-plugin node path/to/my/mini-i18n-extract-plugin-project

🔮 Background

if you're new to Webpack, be sure to check out Webpack's Getting Started guide.

This package was made with the aim of encouraging modularized structure for internationalization data. The use of i18n data shares similarities with how CSS is used. However, different stakeholers need i18n data in different formats:

• For development, modularized and close-to-source structure is preferred.
• For serving the data to end user, files chunks should be split by the usage.
• For translations, having a single source to work with is preferred.

This package addresses the first two of the considerations.

To make an effective use of this, each message / translation should be defined in a single place only. Otherwise the conflicting messages will be overwritten and lead to unexpected results.

🤖 API

TypeDoc documentation can be found here.

Available options are described here.

⏳ Changelog

This projects follows semantic versioning. The changelog can be found here.

🛠 Developing

If you want to contribute to the project or have forked it, this guide will get you up and going.

🏗 Roadmap

There is no explicit roadmap for this project. However, if you have ideas how it could be improved, please be sure to share it with us by opening an issue.

🤝 Contributing

Contributions, issues and feature requests are welcome! Thank you ❤️

Feel free to dive in! See current issues, open an issue, or submit PRs.

How to report bugs, feature requests, and how to contribute and what conventions we use is all described in the contributing guide.

When contributing we follow the Contributor Covenant. See our Code of Conduct.

🧙 Contributors

Contributions of any kind welcome. Thanks goes to these wonderful people ❤️

Recent and Top Contributors

Generated using Hall of Fame.

All Contributors

Contribution type emoji legend

No additional contributors. Be the first one!

This project follows the all-contributors specification.

⭐ Show your support

Give a ⭐️if this project helped you!

🐙 Community

• Stack Overflow
• Quora
• Spectrum community

🔗 Related Projects

• This plugin is based on mini-extract-plugin, a generalized version of mini-css-extract-plugin.
• Generated i18n files can be inlined in HTML generated by html-webpack-plugin using html-webpack-inline-i18n-plugin.

👨‍🔧 Maintainers

👤 Juro Oravec

• Twitter: @JuroOravec
• GitHub: @JuroOravec
• LinkedIn: @jurooravec
• Sourcerer: @JuroOravec

📝 License

Copyright © 2020 Juro Oravec.

This project is MIT licensed.