avaragado / riw

A console app and library to help you localise React apps in conjunction with react-intl

riw

A console app and library to help you localise React apps in conjunction with react-intl

Use riw to:

• Define target locales for your app: the locales into which you translate the app.
• Extract react-intl message descriptors from your React components, directly or indirectly.
• Check for duplicates in your react-intl message descriptor ids if you need to.
• Manage translations for each target locale, storing them in a simple translations database.
• Generate JSON files for your translations, to include in your app.

See Introducing riw on Medium for background and motivations.

There's an example repository, riw-example, showing a simple internationalised React app set up for use with riw.

The word "riw" seems to be Welsh for slope or hill, and rhymes with the English word drew.

This project is not associated with the react-intl project.

Assumptions and prerequisites

riw assumes you're familiar with react-intl, and that your app already uses a build system of some kind (for example, webpack).

riw requires node 8.x or later.

Problems riw doesn't solve

• riw doesn't perform any automated text translation or interface with any translators or translation services. It tells you which messages need translating, lets you update its translations database with the translations once you have them, and produces shippable, react-intl-compatible JSON files for each locale you want to support.

• riw doesn't provide its own mechanism for generating unique react-intl message descriptor ids. However, by default riw uses babel-plugin-react-intl-auto to autogenerate ids. (See the FAQ and https://github.com/akameco/babel-plugin-react-intl-auto for more.)

• riw doesn't import the generated JSON locale files into your app or plug them into react-intl's IntlProvider. You implement this behaviour yourself.

Install

$ yarn add --dev riw  # OR: npm install --save-dev riw

Usage

Full tutorial: Installing, configuring and using riw

TL;DR:

1. Add to your app's package.json:

   "riw": {
       "defaultLocale": "en-US", // locale of source strings
       "targetLocales": [  // other locales app should support
           "fr-FR",
           "pt-BR",
           ...
        ],
   }

2. yarn run riw db init – initialise empty db at src/locale/riw-db.json
3. yarn run riw app translate – outputs src/locale/[locale].json and src/locale/TODO-untranslated.json (you might need to add a .babelrc in your app)
4. Update your app to import strings from src/locale/[locale].json for each target locale, and plug them into react-intl's IntlProvider at the appropriate time.
5. LOOP:
6. Translate everything in the TODO-untranslated.json file. Meanwhile, keep developing your app in the usual way.
7. yarn run riw db import TODO-with-translations.json if you have a file of them in the right format, or
8. yarn run riw db update <opts...> to update the db string by string.
9. yarn run riw app translate
10. Test and (maybe) ship.
11. Go to LOOP.

Check everything into source control. There are no temporary files.

More information

• Configuration settings
• FAQ/troubleshooting
• Using riw programmatically (incomplete)
• Example repository showing how to add react-intl and riw to a React app

Maintainer

David Smith (@avaragado)

Contribute

Bug reports, feature requests and PRs are gratefully received. Add an issue or submit a PR.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Licence

MIT © David Smith

riw's Issues

Use relative paths in TODO file

The file names in TODO-untranslated.json are output as an absolute path. It should use the relative path from the app's root so that the file can be shared among developers.

Support objects as message descriptor description values

react-intl recently added support for arbitrary objects, as well as strings, as the value of a message descriptor's optional description field.

riw currently supports only string values.

In riw, description strings are used as an object key in the translations database JSON file. To support description objects, riw needs some serialisation/deserialisation to/from strings.

Support autogenerated fake/pseudolocales

During i18n, before (complete) l10n, it's often useful to use pseudolocales to simulate common features of languages other than English. For example, German strings are ~30% longer than English, which might affect layout.

riw should ship with some magic pseudolocales that derive algorithmically from the default locale. Possible pseudolocales include:

• reverse: makes it easier to spot text that hasn't been i18n'd
• third-longer: simulates languages like German
• half-length: simulates languages like Japanese

Some sequences in strings need special treatment, such as HTML tags and entities, and arguments in braces.

Support for babel-plugin-react-intl-auto

It would be great if this tool supported babel-plugin-react-intl-auto. It allows ids to be autogenerated based on the file's path.

I installed the plugin and added it to my .babelrc, but it doesn't look like riw is picking up the plugin.

.babelrc

{
  "presets": ["react-app"],
  "plugins": [
    ["react-intl-auto", {
      "removePrefix": "src/",
      "filebase": false
    }]
  ]
}

I dug in a little bit, and it looks like riw uses babel-plugin-react-intl explicitly:

riw/src/lib/riw/app/translate/armdFromSourceFabs.js

Line 17 in d487824

plugins: [pluginReactIntl],

Would it be possible to include additional babel plugins, or am I missing something?

Defer to local package dependency if found and if global

riw can be installed globally or as a package dependency.

If installed globally, and if the CWD is within a package, and if that package has a local riw dependency, then running the global riw should punt to the package dependency.

"--no-progress" option

We use this tool in CI (via module api, not cli). It would be nice if there was a way to disable the status bar output, since when not run in an interactive context, it floods the logs with filename output.

Upgrade babel

Can we upgrade riw's version of babel to v7? Our app uses CRA which is now using the @babel namespace. In order for our tooling to work properly, we have to override the babel-core version in our package.json:

  "resolutions": {
    "**/babel-core": "7.0.0-bridge.0"
  }

I believe this wouldn't be necessary if riw upgraded babel-core to @babel/core.

Of course, doing so will probably require a major version bump...

~ yep, still here using riw! makes my life so much easier.

TypeScript support via a transpile hook?

I just added riw to a project I'm contributing to. (@avaragado - awesome work, thank you for making this! 👏) It's a TypeScript project, so right now there's a transpile-to-JS step that needs to happen before babel (invoked by riw) can extract the strings for localisation.

Since manually invoking the transpilation can easily be forgotten, I was wondering ... if there would be interest in a pre-babel hook implementation in riw that could be configured to run such transpile step automatically? If so I could contribute that in the near future.

Something in the following direction:

/* package.json */
{
  "riw": {
      "transpileCommand": "tsc -p . --target ES6 --module esnext --jsx preserve --outDir tmp/transpiled",
      "sourceDirs": [
        "tmp/transpiled/**/*.js",
        "tmp/transpiled/**/*.jsx"
      ]
   }
}