Documentation Migration guide

Examples:

• Node.js
• Create React App
• Next.js

Note: Original roadmap was deleted because it wasn't updated.

Breaking changes

• [x] #657 Refactor pseudolocale - Migrate existing functionality to support multiple catalogs
• [ ] Release RC 🎉

Documentation

• [ ] Review tutorial
• [x] Review API references, especially macros
• [x] Review migration guide

Nice to have (might be released after v3)

• [x] #656 Refactor catalog stats
• [x] #577 Detect locale from URL, window.navigator or cookies
• [ ] #406 Adds extractId option to conf
• [x] #569 Feature: Merge compiled catalogs into one (feature is finished, it just requires merge latest next branch and resolve conflicts)

If you want to get involved

• [x] #634 Add formatOptions.origin to PO format (copy existing feature from one catalog format to another)
• [x] Review/proofread Configuration reference

Hello, we use lingui v2.9.2 and we got issue extracting using i18n.plural:

This works:

export function _(
  id: MessageDescriptor | string,
  values?: Record<string, unknown>,
  messageOptions?: MessageOptions
): string {
  if (typeof id === 'string') {
    return i18n._(id, values, messageOptions)
  }
  return i18n._(id)
}

This fail:

export function _(id: MessageDescriptor | PluralProps): string {
  return !Object.prototype.hasOwnProperty.call(id, 'one')
    ? i18n._(id as MessageDescriptor)
    : i18n.plural(id as PluralProps)
}

It fails when we run lingui extract --clean, with the following error:

TypeError: src/libs/i18n.ts: undefined is not iterable!
    at module.exports.require.getIterator (/home/dka/workspace/github.com/pass-culture/pass-culture-app-native/node_modules/babel-runtime/node_modules/core-js/library/modules/core.get-iterator.js:5:42)
    at Transformer.transformChoiceMethod (/home/dka/workspace/github.com/pass-culture/pass-culture-app-native/node_modules/@lingui/babel-plugin-transform-js/transformer.js:199:56)
    at Transformer.transformMethod (/home/dka/workspace/github.com/pass-culture/pass-culture-app-native/node_modules/@lingui/babel-plugin-transform-js/transformer.js:393:21)
    at PluginPass.Transformer.transform (/home/dka/workspace/github.com/pass-culture/pass-culture-app-native/node_modules/@lingui/babel-plugin-transform-js/transformer.js:69:25)
    at newFn (/home/dka/workspace/github.com/pass-culture/pass-culture-app-native/node_modules/babel-traverse/lib/visitors.js:276:21)
    at NodePath._call (/home/dka/workspace/github.com/pass-culture/pass-culture-app-native/node_modules/babel-traverse/lib/path/context.js:76:18)
    at NodePath.call (/home/dka/workspace/github.com/pass-culture/pass-culture-app-native/node_modules/babel-traverse/lib/path/context.js:48:17)
    at NodePath.visit (/home/dka/workspace/github.com/pass-culture/pass-culture-app-native/node_modules/babel-traverse/lib/path/context.js:105:12)
    at TraversalContext.visitQueue (/home/dka/workspace/github.com/pass-culture/pass-culture-app-native/node_modules/babel-traverse/lib/context.js:150:16)
    at TraversalContext.visitSingle (/home/dka/workspace/github.com/pass-culture/pass-culture-app-native/node_modules/babel-traverse/lib/context.js:108:19) {
  _babel: true
}

We rather use the synthax of i18n.plural instead of i18n._, how can this be fixed ?

Reproduction

• package.json

git clone https://github.com/pass-culture/pass-culture-app-native.git
cd pass-culture-app-native
nvm use
yarn
yarn run translations:extract

Related issues

• https://github.com/lingui/js-lingui/issues/1020

Discussion for RFC 003: https://lingui.js.org/rfc/003_per_locale_bundles.html

Introduction from RFC

Per-locale bundles are another build time optimization to reduce size of internationalized JavaScript applications.

Consider this example - we have an internationalized app which loads translation from external file:

// src/Notifications.js
import * as React from "react"
import { setupI18n } from "@lingui/core"
import { I18nProvider } from "@lingui/react"
import { Trans, Plural, date } from "@lingui/macro"

const i18n = setupI18n()
i18n.load("cs", import("./locale/cs/messages.json"))
i18n.activate("cs")

const Notifications = ({ now, count }) => (
   <I18nProvider i18n={i18n}>
      <h1><Trans>Notifications</Trans></h1>

      <p><Trans>Today is {date(now)}</Trans></p>

      <p>
         <Plural
            value={count}
            one={<>You have <strong>#</strong> unread notification</>}
            other={<>You have <strong>#</strong> unread notifications</>}
         />
      </p>
   </I18nProvider>
)

If we generate the production bundle in Engish locale, it will roughly look like this - components are removed and formatting components ( and date()) are replaced with runtime versions:

// build/Notifications.en.js
import * as React from "react"
import { Plural, date } from "@lingui/react"

const Notifications = ({ now, count }) => (
   <div>
      <h1>Notifications</h1>

      <p>Today is {date(now)}</p>

      <p>
         <Plural
            value={count}
            one={<>You have <strong>#</strong> unread notification</>}
            other={<>You have <strong>#</strong> unread notifications</>}
         />
      </p>
   </div>
)

So far the code looks very similar to the original one except the loading of message catalogs is removed completely.

Let’s take a look on other than source locale, for example Czech. The message catalog might look similar to this:

msgid "Notifications"
msgstr "Upozornění"

msgid "Today is {now, date}"
msgstr "Dnes je {now, date}"

msgid ""
"{count, plural, "
"one {You have <0>#</0> unread notification} "
"other {You have <0>#</0> unread notification}}"
msgstr ""
"{count, plural, "
"one {Máte <0>#</0> nepřečtenou zprávu} "
"few {Máte <0>#</0> nepřečtené zprávy} "
"other {Máte <0>#</0> nepřečtených zpráv}}"

If we generate the production bundle for Czech locale, it will look roughly like this - translations are applied at build time. Also, has all locale specific plural rules:

// build/Notifications.cs.js
import * as React from "react"
import { Plural, date } from "@lingui/react"

const Notifications = ({ now, count }) => (
   <div>
      <h1>Upozornění</h1>

      <p>Dnes je {date(now)}</p>

      <p>
         <Plural
            value={count}
            one={<>Máte <strong>#</strong> nepřečtenou zprávu</>}
            few={<>Máte <strong>#</strong> nepřečtené zprávy</>}
            other={<>Máte <strong>#</strong> nepřečtené zprávy</>}
         />
      </p>
   </div>
)

Per-locale bundles has zero footprint of internatinalization library - the code looks exactly the same have it would look like when no internationalization was used at all. The remaining runtime layer are utilities for formatting like plurals, dates and number formatting. There’s also no extra request to fetch locale files and no runtime parsing.

No messages get extracted when using:

import i18n from './utils/i18n'
import {t} from '@lingui/macro';

i18n._(t`hello`)

They get extracted when using it like:

i18n._("hello")

They also get extracted as expected when using a react component:

import {Trans} from '@lingui/react';

<Trans>Hello</Trans>

any ideas?

Describe the bug When running lingui extract I get the error Duplicate declaration "Trans" ("t" seems to be OK).

To Reproduce

Cannot process file /<path>.tsx: Duplicate declaration "Trans"
  15 | // i18n
  16 | import { useI18N, Locale } from 'i18n';
> 17 | import { t, Trans } from '@lingui/macro';

Expected behavior No error on lingui extract

Additional context

• Tried v3.4.0 and still had issues
• CLI version v3.2.1 repros the issue
• CLI version v3.1.0 does not repro the issue
• @babel/[email protected]
• Using Lingui in a NextJS project
• Looked at the diff (https://github.com/lingui/js-lingui/compare/v3.1.0...v3.2.1) and there are two changes that jump out, but I don't understand the code enough to troubleshoot part this point. (https://github.com/lingui/js-lingui/pull/846 and https://github.com/lingui/js-lingui/pull/854) (cc @semoal and @Bertg in case they have any ideas)
• .babelrc

{
  "presets": ["next/babel"],
  "plugins": ["macros"],
  "env": {
    "test": {
      "plugins": ["dynamic-import-node"]
    }
  }
}

Describe the bug Running lingui extract results in error

Error: EPERM: operation not permitted, scandir 'C:/$Recycle.Bin/S-1-5-18'

To Reproduce Use next-js example, and run lingui extract

Expected behavior The command should run successfully.

• jsLingui version 3.0
• Babel version @babel/[email protected]
• Your Babel config (e.g. .babelrc):

{
    "presets": ["next/babel"],
    "plugins": [
      "macros",
      "jsx-control-statements",
      [
        "import",
        {
          "libraryName": "@geist-ui/react",
          "libraryDirectory": "esm"
        }
      ]
    ]
  }
  

Hi & thanks for your work on this project! While looking for a new localization solutions for our React frontend, we found this project and liked the approach. Our goal is to use po files to leverage comments for providing context for translators (and our future selves…). We started with the @next branch since that's the natual way to go forward. Despite some rough edges regarding the documentation and typescript typings, we were very happy with the functionality of this solution.

Problem

Our only major pain point (besides the removal of the /* i18n: Comment */t("id")`Translated string`; syntax from version 2.x ;)) is that the po file format does not support the "native" plurals with msgstr[0], msgstr[1] etc. Unfortunately, we were not able to find an online translation service that was able to handle ICU plural strings when embedded in po files. The situation may be different with JSON documents, but then we'd loose comment functionality.

We noticed that other user have already encountered the same problem, unfortunately without an obvious solution: #595 & #82 (where it is mentioned that there are services that understand ICU, but as I said, we weren't able to find any that support ICU in PO)

Approach

After some experimenting, we decided to give a try at implementing rudimentary ICU -> PO -> ICU transformation for the po format. This PR shows the modifications that were required. In short, the new code transforms the following ICU into the corresponding PO plurals (and back):

{
    "message_id": {
        "message": "{count, plural, one {Singular Case} two {Case for two} other {Case for {count} other}}"
    }
}

msgctxt "pluralize_on=count"
msgid "message_id"
msgid_plural "message_id"
msgstr[0] "Singular Case"
msgstr[1] "Case for two"
msgstr[2] "Case for {count} other"

To be discussed

1. What to use as msgid_plural?

Currently, the code uses msgid_plural to tell the world that a message is pluralized. When a custom ID is used, it uses the same ID as msgid_plural.

As of right now, for automatic IDs (where the message is also its ID), the last plural case taken from the ICU message format is used as msgid_plural, but I don't know if that's the right decision as it reads somewhat strange when the regular msgid is the full ICU message and the msgid_plural is only an excerpt from that.

2. Is msgctxt the right place to store pluralization key?

Since the ICU format is more powerful than PO plurals, we need to somehow remember the placeholder used to pluralize the message to transform the message back to the ICU format. It might be possible to parse it from the translations, but not in all cases. (Might not be used in all/any translation, multiple placeholders might be used but we can't know which is the one for localization...)

As a workaround, I've chosen to store the pluralization key in the PO item's msgctxt. What do you think about that? Should we rather use a special comment line for that purpose?

3. How to opt in or out of this process?

While we think that this new way of using PO plurals is "more correct" than embedding ICU messages in PO, it might not be suitable for everyone and brake the workflow for people with functioning translation tools that understand ICU within PO (whatever tools that are).

What do you think would be good way to integrate this? As a new format (po_with_plurals?) As the default and the old po parsers is then referred to as po_icu?

Summary

If you decide that we can go forward with this I'll gladly add tests for the new warning outputs that have not been automatically tested yet. The transforms themselves are covered in two added test cases as you can see in the diff.

We'd like to hear what you think about these changes and whether you could see them land in lingui.

Describe the bug I followed the React tutorial instructions to add js-lingui to my Gatsby v1 app (including npm install --global babel-core@^7.0.0-0 @babel/core), but when running lingui extract I get Cannot find module 'babel-core'.

I'm very rusty with Node development so I might have misunderstood something!

To Reproduce See this repo. yarn + gatsby develop works, the app runs as expected, but I get the above error when running lingui extract to regenerate the message catalog.

Expected behavior lingui extract should succeed.

Additional context lingui --version: 2.4.1

$ npm list babel-core @babel/core
[email protected] /Users/sdubois/Repos/lingui-babel-debug
├── @babel/[email protected]
├─┬ [email protected]
│ └─┬ [email protected]
│   └── [email protected]  deduped
├─┬ [email protected]
│ └── [email protected]  deduped
└─┬ [email protected]
  ├── [email protected]  deduped
  └─┬ [email protected]
    └─┬ [email protected]
      └─┬ [email protected]
        └─┬ [email protected]
          └── [email protected]  deduped

$ npm list -g babel-core @babel/core
/usr/local/lib
├── @babel/[email protected]
└── [email protected]

lingui 2.0.4, babel 7.0.0-beta.40

> lingui extract --clean

Extracting messages from source files…
/code/App/node_modules/@babel/core/lib/config/config-descriptors.js:158
    throw new Error("Plugin/Preset files are not allowed to export objects, only functions.");
    ^

Error: Plugin/Preset files are not allowed to export objects, only functions.
    at createDescriptor (/code/App/node_modules/@babel/core/lib/config/config-descriptors.js:158:11)
    at /code/App/node_modules/@babel/core/lib/config/config-descriptors.js:101:12
    at Array.map (<anonymous>)
    at createDescriptors (/code/App/node_modules/@babel/core/lib/config/config-descriptors.js:100:27)
    at createPresetDescriptors (/code/App/node_modules/@babel/core/lib/config/config-descriptors.js:92:10)
    at /code/App/node_modules/@babel/core/lib/config/config-descriptors.js:64:19
    at presets (/code/App/node_modules/@babel/core/lib/config/config-descriptors.js:54:25)
    at mergeChainOpts (/code/App/node_modules/@babel/core/lib/config/config-chain.js:294:68)
    at /code/App/node_modules/@babel/core/lib/config/config-chain.js:247:7
    at buildRootChain (/code/App/node_modules/@babel/core/lib/config/config-chain.js:83:20)

There's a closed issue mentioning something like this: https://github.com/lingui/js-lingui/issues/163

The difference is that I actually updated to 2.0.4 from 2.0.0 and got this error (while the author of issue#163 had an opposite situation - he was getting this on 2.0.2 and it was "fixed" and updated to 2.0.4)

Any ideas how to fix that?

Getting this error when running command to add a new locale:

$ lingui add-locale cs
fs.js:653
  return binding.open(pathModule._makeLong(path), stringToFlags(flags), mode);
                 ^

Error: ENOENT: no such file or directory, open 'C:\<projectDir>\locale\cs\messages.json'
    at Object.fs.openSync (fs.js:653:18)
    at Object.fs.writeFileSync (fs.js:1300:33)
    at Object.write (C:\<projectDir>\node_modules\lingui-cli\dist\api\formats\lingui.js:60:20)
    at Object.addLocale (C:\<projectDir>\node_modules\lingui-cli\dist\api\formats\lingui.js:162:14)
    at C:\<projectDir>\node_modules\lingui-cli\dist\lingui-add-locale.js:29:36
    at Array.map (<anonymous>)
    at command (C:\<projectDir>\node_modules\lingui-cli\dist\lingui-add-locale.js:28:25)
    at Object.<anonymous> (C:\<projectDir>\node_modules\lingui-cli\dist\lingui-add-locale.js:68:3)
    at Module._compile (module.js:624:30)
    at Object.Module._extensions..js (module.js:635:10)
error Command failed with exit code 1.

lingui-cli 1.3.7 windows 10 (tried both from command prompt and git bash)

Describe the bug When using i18n._ with the second argument "values" those values are not inserted into the string in production build, but they are inserted into the string in development when running npm run start.

To Reproduce I have created a sample repository that can be used to reproduce the problem:

https://github.com/nmoinvaz/lingui-values-bug

Relevant code file: https://github.com/nmoinvaz/lingui-values-bug/blob/main/src/App.js

• npm install
• npm run start

In development the strings are properly replaced:

• npm build
• serve -s build

In production the strings are not properly replaced:

Expected behavior The values object should be inserted into the string. For example {a} should be replaced with 1.

Additional context

• ling-ui version 3.9.0
• Create React App

This closes #1326 by implementing a command specific for Windows to do the git update-index marking and unmarking files magic. Furthermore, I had to change the LERNA_COMMAND to plain npx lerna to get it working on Windows.

Describe the bug The local development described in CONTRIBUTING.md doesn't work on Windows as the mentioned script verdaccio-release.js is heavily based on Linux platform.

To Reproduce Clone repository and try to set-up local development environment as described in CONTRIBUTING.md on a Windows platform.

Expected behavior The local development environment should work on Windows platform.

Example from documentation:

import { Select } from "@lingui/macro"

// gender == "female"      -> Her book
// gender == "male"        -> His book
// gender == "unspecified" -> Their book
<Select
    value={gender}
    male="His book"
    female="Her book"
    other="Their book"
/>

Actually, it should be:

import { Select } from "@lingui/macro"

<Select
    value={gender}
    _male="His book"
    _female="Her book"
    other="Their book"
/>

Proof: https://github.com/lingui/js-lingui/blob/main/packages/macro/test/jsx-select.ts#L3-L19

If you write code as in example, macro will produce:

import { Trans } from "@lingui/react";
<Trans
+  male="He"
+  female={`She`}
  id={"{count, select, male {He} female {She} other {<0>Other</0>}}"}
  values={{
    count: count,
  }}
  components={{
    0: <strong />,
  }}
/>;

Which by the way will work, but unnecessary code would be produced.

So here we should either fix the macro to not produce this fields and add this to the test case. Or update docs and fix usage with _{option} which would be a breaking change.

Anyway, action point needed here.

I'm continuing digging into the sourcecode and test suite. Here what i've found:

According to the exported typings all JSX Macro components (Trans, Plural, etc) have common Trans props, which is following:

export type TransProps = {
  id?: string
  comment?: string
  values?: Record<string, unknown>
  context?: string
  children?: React.ReactNode
  component?: React.ComponentType<TransRenderProps>
  render?: (props: TransRenderProps) => ReactElement<any, any> | null
  i18n?: I18n
}

export type ChoiceProps = {
  value?: string | number
} & TransProps &
  ChoiceOptions<ReactNode>

export type SelectProps = {
  value: string
  other: ReactNode
} & TransProps & Values

export const Trans: ComponentType<TransProps>
export const Plural: ComponentType<ChoiceProps>
export const Select: ComponentType<SelectProps>
export const SelectOrdinal: ComponentType<ChoiceProps>

This is actually wrong, because JSX Macro (from the source code and tests) could accept only this set properties:

export type TransProps = {
  id?: string
  comment?: string
-  values?: Record<string, unknown>
  context?: string
-  children?: React.ReactNode // should be only for Trans, not by any other Choice components
-  component?: React.ComponentType<TransRenderProps>
  render?: (props: TransRenderProps) => ReactElement<any, any> | null
-  i18n?: I18n
}

So passing any of the properties highlihted in the snippet above will not work. These typings just bring mess and confusing for end users. (it's actually props of original Trans runtime component, not a macro).

Proofs: https://github.com/lingui/js-lingui/blob/main/packages/macro/src/macroJsx.ts#L179-L194 Other properties would stripped or inlined as choice options in ICU Choice component.

Am i missing something or it's here by historical reasons and a just need to be cleaned up wisely?

While writing SWC Macro plugin and reading babel macro source code found this in tests:

export default [
  {
    name: "Arg macro should be exluded from values",
    input: `
        import { t, arg } from '@lingui/macro';
        const a = t\`Hello $\{arg('name')\}\`;
    `,
    expected: `
        import { i18n } from "@lingui/core";
        const a = 
          /*i18n*/
          i18n._("Hello {name}")
    `,
  },
]

Which is not described anywhere. Or if it's outdated - should be removed from codebase.