From 075363d729790c33f514523c8da800321ce78cb6 Mon Sep 17 00:00:00 2001 From: GweesinChan Date: Tue, 10 Dec 2024 22:10:00 +0800 Subject: [PATCH] feat: support localization for rule messages --- .../2024-support-l10n-rule-messages/README.md | 185 ++++++++++++++++++ 1 file changed, 185 insertions(+) create mode 100644 designs/2024-support-l10n-rule-messages/README.md diff --git a/designs/2024-support-l10n-rule-messages/README.md b/designs/2024-support-l10n-rule-messages/README.md new file mode 100644 index 00000000..8440ffe4 --- /dev/null +++ b/designs/2024-support-l10n-rule-messages/README.md @@ -0,0 +1,185 @@ +- Repo: eslint/eslint +- Start Date: 2024-12-09 +- RFC PR: (leave this empty, to be filled in later) +- Authors: [gweesin](https://github.com/gweesin) + +# Support Localization of Rule Messages + +## Summary + + + +This RFC proposes adding support for localization of rule messages in ESLint. The goal is to allow users to provide translations for rule messages, enabling ESLint to display messages in different languages based on user preferences. This feature aims to improve the accessibility and usability of ESLint for non-English speaking users. + +## Motivation + + + +The primary motivation for this feature is to make ESLint more accessible to a global audience. Currently, ESLint rule messages are only available in English, which can be a barrier for non-English speaking users. By allowing rule messages to be localized, we can improve the user experience for developers who prefer to work in their native language. This change will help ESLint reach a broader audience and make it easier for developers around the world to understand and fix linting issues in their code. + +## Detailed Design + + + +To implement localization of rule messages in ESLint, we will support two ways to define the localization information: + +1. Support for plugin definition messages with locale files. + plugins can define localized messages directly within their rule definitions so that all the messages can be supported in the same repository. This approach allows plugin authors to provide translations for their rule messages without relying on external files. + + Example: + + ```js + module.exports = { + meta: { + messages: { + someMessageId: { + en: "Default message in English", + es: "Mensaje predeterminado en español" + } + } + }, + create(context) { + return { + Identifier(node) { + context.report({ + node, + messageId: "someMessageId" + }); + } + }; + } + }; + ``` + +2. Support a way using `eslint.config.js` file to configure message info by message ID. + This way should allow users to provide some plugins to update other plugins' messages. This approach allows users to customize the messages for rules provided by plugins. + + Example: + + ```js + module.exports = { + locale: "es", + rules: [/* ... */], + messages: { + "plugin/ruleId": { + someMessageId: "Mensaje predeterminado en español" + } + } + }; + ``` + + and eslint will use the message info to replace the message in the rule if the message ID is found in the configuration. + +for corner cases, we need to consider the following: + +1. If a translation is missing for a specific language, ESLint should fall back to the default English message. +2. ESLint should support original flat rules structure and the new structure with localized messages. + +## Documentation + + + +1. Update the official ESLint documentation to include information on how to create and use localization files. +2. Provide examples and guidelines for contributing translations, including third party integrations. + +## Drawbacks + + + +1. Increased Maintenance Burden: Adding support for localization will increase the complexity of the ESLint codebase. Maintaining translations and ensuring they are up-to-date with rule changes will require additional effort from both the core team and contributors. +2. It's better to use a module to handle the localization such as typescript using `@types/some-module` but it's not possible to use a module to handle the localization in ESLint. +3. Potential for Incomplete Translations: There is a risk that some languages may have incomplete translations, leading to a mix of localized and default English messages. + This could confuse users and reduce the overall effectiveness of the feature. + +## Backwards Compatibility Analysis + + + +This change should not affect existing ESLint users who do not use the localization feature. Users who do not provide translations will continue to see the default English messages. To minimize disruption, ESLint should provide clear documentation on how to create and use localization files, as well as guidelines for contributing translations. + +## Alternatives + + + +1. TypeScript `--locale` option: This option allows users to specify the locale for the TypeScript compiler, which affects the language service features. However, this approach is limited to the TypeScript compiler and does not provide a general solution for localization in ESLint. + > [TypeScript compiler options](https://www.typescriptlang.org/docs/handbook/compiler-options.html#compiler-options) + > https://github.com/eslint/eslint/issues/9870#issuecomment-359228967 + + why not? because almost all the messages are provided by third party plugins, so it's not possible to handle the localization in the core. + +2. Is it possible to check `@locale/module` in the same way as `@type/module`? + +## Open Questions + + + +## Help Needed + + + +I sure I can implement this RFC on my own. + +## Frequently Asked Questions + + + +## Related Discussions + + + +- https://github.com/eslint/eslint/issues/19210 +- https://github.com/eslint/eslint/issues/9870 \ No newline at end of file