I18next-cli Bug: Domain Prefix Parsing Issue In V1.16.0

Hey everyone, let's dive into a pesky bug that's been causing some headaches in i18next-cli versions starting from v1.16.0. It's all about how the CLI handles domain prefixes when you're using the useTranslation hook and the t function. Basically, the CLI is getting confused and treating your domain prefixes as part of the translation key, which is definitely not what we want! This leads to some wonky JSON output in your translation files. Don't worry, we'll break down the issue, how to reproduce it, and what the expected behavior should be. Ready to get started?

The Bug: Domain Prefix Mishap

So, here's the deal, i18next-cli is misinterpreting the domain prefixes. When you pass a domain to both useTranslation and the t function (as a prefix), the CLI gets tripped up. Instead of neatly organizing your translations, it starts nesting them in a way that includes the domain name as a level in your JSON structure. This is a real problem, especially when you're trying to keep your translation files organized and easy to manage. The strange part? This bug doesn't seem to affect the Trans component. Let's dig deeper into how this happens.

To really understand the issue, imagine you're working with a myDomain domain. You might expect your translation file (src/i18n/locales/en/myDomain.json) to look something like this:

{
  "foo1": {
    "bar1": "myDomain:foo1.bar1"
  },
  "foo2": {
    "bar2": "myDomain:foo2.bar2"
  }
}

However, due to the bug, you end up with something like this instead:

{
  "foo1": {
    "bar1": "myDomain:foo1.bar1"
  },
  "myDomain": {
    "foo2": {
      "bar2": "foo2.bar2"
    }
  }
}

See that "myDomain" nesting? That's the bug in action. It's messing up the structure, and making it harder to manage your translations. It means you'll have to adjust how you write your keys and how you reference them, adding extra steps to what should be a smooth process. This regression is a major headache, especially as you upgrade to newer versions of i18next-cli.

Code Snippet of the bug

Let's take a look at the i18next.config.ts configuration file that's causing trouble. Here’s a basic setup that defines the input, output, and other key settings for how the CLI extracts translations. Notice the functions array which specifies how the translation keys are identified. This is where we tell i18next-cli to look for t and other translation functions. The inclusion of transComponents tells the CLI to look for the Trans component too. The bug here lies in how the domain is being processed during key extraction when used in conjunction with the t function.

// i18next.config.ts
import { defineConfig } from 'i18next-cli';

export default defineConfig({
  locales: 'en',
  extract: {
    input: 'src/**/*.{js,jsx,ts,tsx}',
    output: 'src/i18n/locales/{{language}}/{{namespace}}.json',
    defaultNS: 'translation',
    functions: ['t', '*.t'],
    transComponents: ['Trans'],
    sort: false
  },
});

Next, here's the code from your component file. This is where you call the useTranslation hook, pass the domain, and use the t function. The Trans component is also used to illustrate the difference in behavior. As you can see, the Trans component works as expected, but the t function prefixes the key with the domain in an unwanted way.

// Component.tsx
import { useTranslation, Trans } from 'react-i18next';

const MyComponent = async ({ params: { lng } }: { params: { lng: string } }) => {
  const { t } = await useTranslation(params.lng, 'myDomain');

  return (
    <>
      <Trans i18nKey='myDomain:foo1.bar1' t={t} />
      {t('myDomain:foo2.bar2')}
    </>
  );
};

Step-by-Step Reproduction

Let’s walk through the reproduction steps to make sure we're all on the same page. First, you set up your i18next.config.ts file, making sure it correctly specifies where your source code is, where your output translation files should go, and which functions and components to consider when extracting translations. Then, you create a component in your application, like the MyComponent example above, that uses both the useTranslation hook and the t function, along with a domain prefix. You include both Trans component usage and direct t function calls to see the discrepancy. Finally, you run the i18next-cli command to extract the translations. When you check the output JSON, you'll see the problematic nesting.

Expected vs. Actual Behavior

When we set up our code, we expect a nice, clean translation file where the keys are correctly structured, and domains don't create unnecessary nesting. The Trans component's behavior is consistent and correct. Ideally, when using t('myDomain:foo2.bar2'), the output in your JSON file should be straightforward, without any unexpected domain-related nesting. This makes it easier to manage translations and keeps your codebase tidy. Unfortunately, in v1.16.0 and later, the actual behavior introduces the domain prefix as a level in the JSON structure. This results in the nested structure that's shown in the original bug report. This difference between the expected and actual behaviors makes it more difficult to integrate and maintain translations, which is critical for any internationalized app. This unexpected nesting adds complexity and requires a workaround.

Troubleshooting and Workarounds

So, what can we do? Since this is a bug in the i18next-cli, the best long-term solution is to wait for a fix in a future version. But, let's look at a few workarounds in the meantime. One immediate workaround might be to avoid using domain prefixes altogether with the t function. Instead, you can rely on namespaces to organize your translations, or you can use the Trans component, which doesn't seem to have the same issue. If you really need to use domain prefixes, you might need to manually edit the generated JSON files after running the CLI. This is not ideal, but it's a way to maintain the correct structure until the issue is resolved. Also, ensure your i18next and i18next-cli versions are compatible, and double-check your configuration file for any typos or misconfigurations that might contribute to the issue. Keep an eye on the i18next-cli repository for updates and any potential fixes.

Your Environment Details

Knowing your environment is key when troubleshooting this kind of bug. In this case, the bug has been reported with the following setup:

• Node.js: Version 22.21.1
• i18next: Version 25.6.2
• Operating System: macOS
• Affected i18next-cli versions: >= 1.16.0

If you are using this version, it's possible that you are experiencing the same issue.

Conclusion

Alright, folks, we've covered the i18next-cli bug where domain prefixes are incorrectly parsed as part of the translation key, leading to messed-up JSON files. We've explored the problem, shown you how to reproduce it, and looked at what's supposed to happen versus what actually happens. Remember to check out the troubleshooting steps, potential workarounds, and environment details. Keep an eye on the i18next-cli repository for updates! Stay tuned, and happy coding!