Structuring messages by component name

[amannn]

In the docs, we recommend structuring messages by component name.

Components are the main concept for code reuse in React apps and we can piggyback on that for message reuse.

It’s a constraint, but I believe it results in a simpler mental model with a guarantee to know which message is used where. Also, this results in somewhat shorter message keys in components.

Since this is entirely optional, I'd be curious about how many people use this pattern, if you've encountered problems, or if you prefer an entirely different pattern and why.

[ThePatriczek]

I like the pattern. So I have an idea, what about structuring files for messages inside folder of a component and load it dynamically to the config (somehow)? @amannn

Something like this

Now you can use multiple files per locale (https://next-intl-docs-git-docs-app-router-first-next-intl.vercel.app/docs/configuration#messages), but I think it could be imported to the config (and also types) automatically (hierarchically) by some pattern (e.g. **/specificFolderName/*.json)

[ThePatriczek]

I wrote simple generator for this problem

configGenerator.js

const fs = require('fs');
const path = `${process.cwd()}/app`;
const files = [];

const fillFiles = function (path, files) {
    fs.readdirSync(path).forEach(function (file) {
        const subpath = path + '/' + file;

        if (fs.lstatSync(subpath).isDirectory()) {
            fillFiles(subpath, files);
        } else if (subpath.includes(`messages`) || subpath.includes(`_messages`)) {
            files.push(path + '/' + file);
        }
    });
};

fillFiles(path, files);

const getRelativePathAfterAppDir = (file) => {
    return file.split('app/')[1];
};

const mergedFiles = [
    ...new Set(
        files.map((file) => {
            const fileName = file.split('/').pop();
            const fileExtension = fileName.split('.').pop();
            // replace file name with index
            return file.replace(fileName, `\${locale}\.${fileExtension}`);
        })
    ),
].reverse();

const generateConfigFile = () => {
    fs.writeFileSync(
        `${process.cwd()}/app/i18n/i18n.generated.ts`,
        `export const getGeneratedMessagesConfig = async ({ locale }) => {
    ${mergedFiles
        .map((file, index) => {
            const path = getRelativePathAfterAppDir(file);
            return `const file${index} = (await import(\`./${path}\`)).default;`;
        })
        .join('\n    ')}
        
    return {
        messages: { 
            ${mergedFiles
                .map((file, index) => {
                    return `...file${index}`;
                })
                .join(',\n            ')},
        },
    };
};
`
    );
};

generateConfigFile();

i18n.generated.ts

export const getGeneratedMessagesConfig = async ({ locale }) => {
    const file0 = (await import(`./_messages/${locale}.json`)).default;
    const file1 = (await import(`./[locale]/table/_components/LeftPanel/messages/${locale}.json`)).default;
        
    return {
        messages: { 
            ...file0,
            ...file1,
        },
    };
};

typesGenerator.js

const fs = require('fs');
const path = `${process.cwd()}/app`;
const files = [];

const fillFiles = function (path, files) {
    fs.readdirSync(path).forEach(function (file) {
        const subpath = path + '/' + file;

        if (fs.lstatSync(subpath).isDirectory()) {
            fillFiles(subpath, files);
        } else if (subpath.includes(`messages`) || subpath.includes(`_messages`)) {
            files.push(path + '/' + file);
        }
    });
};

fillFiles(path, files);

const getRelativePathAfterAppDir = (file) => {
    return file.split('app/')[1];
};
const generateTypesFile = () => {
    fs.writeFileSync(
        `${process.cwd()}/i18n.generated.d.ts`,
        `${files
            .map((file, index) => {
                const path = getRelativePathAfterAppDir(file);
                return `type file${index} = typeof import('@/${path}');`;
            })
            .join('\n')}\ndeclare interface IntlMessages extends ${files
            .map((file, index) => `file${index}`)
            .join(', ')} {}\n`
    );
};

generateTypesFile();

i18n.ts

import { getRequestConfig } from 'next-intl/server';
import { getGeneratedMessagesConfig } from './i18n.generated';

export default getRequestConfig(async (args) => {
    const generatedMessagesConfig = await getGeneratedMessagesConfig(args);

    return {
        ...generatedMessagesConfig,
    };
});

i18n.generated.d.ts

type file0 = typeof import('@/[locale]/table/_components/LeftPanel/messages/cs.json');
type file1 = typeof import('@/[locale]/table/_components/LeftPanel/messages/en.json');
type file2 = typeof import('@/_messages/cs.json');
type file3 = typeof import('@/_messages/en.json');
declare interface IntlMessages extends file0, file1, file2, file3 {}

[amannn]

Oh wow, that's really cool—thank you for sharing this! If that works well for you, it's definitely ok!

Personally, I find it helpful to have a single large messages file, since it appears easier to integrate with translation management systems to me and also the IDE workflow can be streamlined.

[ThePatriczek]

That integration with VSCode is awesome, unfortunately I use WebStorm, are you planning create integration for the Jetbrains IDE either? @amannn

[ThePatriczek]

In my opinion it’s important to leave files together inside the component. I always prefer package by "feature" (component) based project organization, so I have component that has own style, hook, graphql fragment and "view" (jsx) and now also translations inside the same folder. @amannn

[amannn]

Sure, that's definitely a valid approach if it's helpful to you!

It seems like i18n ally is supported in JetBrains IDEs too, yes: https://i18nally.org/. Support has still yet to land though!

[RaenonX]

Redirected from #425.

I like the idea of structuring the message by component name I think it would be critical to keep this optional instead of required.

One of the reasons to keep it optional instead of required is because my app uses some translation that is shared across components/pages. Taking my game info app as an example, the translation of an item must be the same in the same locale, but these items could show up in different pages, so there's no point making them into separate translations.

[heloineto]

I don't like this pattern because it makes refactoring component (renaming, splitting into smaller components, etc...) a big pain.

Also it's ackward if I have the same text for two different components.

[heloineto]

I would really like to have an option to put the translations like so:

import { useTranslations } from 'next-intl';

export default function Page() {
  const t = useTranslations();

  return <div>{t({ en: 'Title', de: 'Titel' })}</div>;
}

The advantages of this patterns are:

1. It's composable
2. No need create names for the strings
3. No need to jump trough files
4. Plays very nicely with Gihub Copilot (This is huge for me)

Disadvantages are:

1. Takes more space on the component (even more if the app supports a lot of languages)
2. Takes more memory for client components

[markomitranic]

One of the things I learned (from others, but also the hard way) working for years with large translation codebases is that you should never (with some global exceptions) reuse translations across components or pages.

I absolutely love the idea proposed here as a developer, it just feels right. I have, however, worked with enough translators and translation software, to know that:

1. As your system grows, you will move away from translation files to a cloud based translation saas
2. Translators want all of their stuff in the same place, they also love having the context of the usage of the component on page (or pages).

Both of this seem nearly impossible with the proposed setup :(

[neemski]

Apologies if this has been brought up already (I couldn't find any existing discussions here about this), but I really prefer the developer experience with libraries like react-intl and lingui, where they can automatically generate message IDs based on the content of the translation, rather than manually specifying an ID. Really helps speed up the dev process and improves readability of components when you have immediate feedback of what the user will see in your default locale.

Are there any plans to support automatic message ID generation in the future, with this library?

[markomitranic]

@neemski that is completely understandable, which is why we have multiple libraries :) I can definitely see the value in what you propose, but that sounds much more like a VSCode extension than a next-intl thing. You basically need a slugifier to run and add KV pairs to the messages files. In a very similar way, I use https://www.i18n.studio/ to automate adding keys (and autogenerating values) for 24 languages on the current project i work on.

I can't speak on if amann will add such a thing but I can try to bring some light on how i see value of this. As someone who has worked with translations a lot over the past 10 years, with at least 3 large projects having more than 20 languages and external translators - the way next-intl does it is fairly standard across the industry. It is also the way large companies like Netflix and Apple do it (as personally confirmed by persons I know) At any larger scale, you will want to very explicitly control the keys. Naming a key is akin to naming a variable in our code, and should not be done in a hurry, companies have whole systems relying on these names. From designers using them in Figma, to external translation companies using specialized software that can ingest pot, xml or json files and use variable names as human-readable identifiers.

Opinions vary, but some of the best industry practices are to separate "translation domains" with dots, use camelcase, never reuse keys, never programmatically invoke keys, never rename keys, use names that explain the position and intent of the usage instead of the actual value etc. It is often said that "keys have nothing to do with the translations, in the same way that a variable name has nothing to do with the content".

So, as you can see, in the wider industry (including other major language ecosystems that are much more mature at this sort of thing) you generally first define a key, the key belongs to you - the developer :D it is only after that, that a designer, and then army of translators, creates the actual labels.

[amannn]

@markomitranic Thanks a bunch for sharing your thoughts here, you clearly have a lot of experience in this area! Also cool to hear that this seems to match the learnings I've made over the years.

Have you ever thought about writing this down into a long-form blog post? At least for my part, I'd find that really insightful—and I know your blog posts are always fun to read :). I haven't seen this topic to be talked about much, but I also believe it's quite an important aspect for keeping code bases maintainable. The closest I've seen so far is The Key to Translation: The Ultimate Guide to Naming Translation Keys from the friends over at Tolgee.

@neemski I'm on the same page here as @markomitranic, personally I find an editor integration to be really helpful in terms of DX. That being said, other community members have expressed a desire for message extraction. It's not something I'm planning to look into for the time being, but there might be room for a community-based solution.