Skip to content

Commit 075363d

Browse files
gweesingweesin
committed
feat: support localization for rule messages
1 parent 8265809 commit 075363d

File tree

1 file changed

+185
-0
lines changed
  • designs/2024-support-l10n-rule-messages

1 file changed

+185
-0
lines changed

Diff for: ‎designs/2024-support-l10n-rule-messages/README.md

+185
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
- Repo: eslint/eslint
2+
- Start Date: 2024-12-09
3+
- RFC PR: (leave this empty, to be filled in later)
4+
- Authors: [gweesin](https://github.com/gweesin)
5+
6+
# Support Localization of Rule Messages
7+
8+
## Summary
9+
10+
<!-- One-paragraph explanation of the feature. -->
11+
12+
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.
13+
14+
## Motivation
15+
16+
<!-- Why are we doing this? What use cases does it support? What is the expected
17+
outcome? -->
18+
19+
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.
20+
21+
## Detailed Design
22+
23+
<!--
24+
This is the bulk of the RFC.
25+
26+
Explain the design with enough detail that someone familiar with ESLint
27+
can implement it by reading this document. Please get into specifics
28+
of your approach, corner cases, and examples of how the change will be
29+
used. Be sure to define any new terms in this section.
30+
-->
31+
32+
To implement localization of rule messages in ESLint, we will support two ways to define the localization information:
33+
34+
1. Support for plugin definition messages with locale files.
35+
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.
36+
37+
Example:
38+
39+
```js
40+
module.exports = {
41+
meta: {
42+
messages: {
43+
someMessageId: {
44+
en: "Default message in English",
45+
es: "Mensaje predeterminado en español"
46+
}
47+
}
48+
},
49+
create(context) {
50+
return {
51+
Identifier(node) {
52+
context.report({
53+
node,
54+
messageId: "someMessageId"
55+
});
56+
}
57+
};
58+
}
59+
};
60+
```
61+
62+
2. Support a way using `eslint.config.js` file to configure message info by message ID.
63+
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.
64+
65+
Example:
66+
67+
```js
68+
module.exports = {
69+
locale: "es",
70+
rules: [/* ... */],
71+
messages: {
72+
"plugin/ruleId": {
73+
someMessageId: "Mensaje predeterminado en español"
74+
}
75+
}
76+
};
77+
```
78+
79+
and eslint will use the message info to replace the message in the rule if the message ID is found in the configuration.
80+
81+
for corner cases, we need to consider the following:
82+
83+
1. If a translation is missing for a specific language, ESLint should fall back to the default English message.
84+
2. ESLint should support original flat rules structure and the new structure with localized messages.
85+
86+
## Documentation
87+
88+
<!--
89+
How will this RFC be documented? Does it need a formal announcement
90+
on the ESLint blog to explain the motivation?
91+
-->
92+
93+
1. Update the official ESLint documentation to include information on how to create and use localization files.
94+
2. Provide examples and guidelines for contributing translations, including third party integrations.
95+
96+
## Drawbacks
97+
98+
<!--
99+
Why should we *not* do this? Consider why adding this into ESLint
100+
might not benefit the project or the community. Attempt to think
101+
about any opposing viewpoints that reviewers might bring up.
102+
103+
Any change has potential downsides, including increased maintenance
104+
burden, incompatibility with other tools, breaking existing user
105+
experience, etc. Try to identify as many potential problems with
106+
implementing this RFC as possible.
107+
-->
108+
109+
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.
110+
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.
111+
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.
112+
This could confuse users and reduce the overall effectiveness of the feature.
113+
114+
## Backwards Compatibility Analysis
115+
116+
<!--
117+
How does this change affect existing ESLint users? Will any behavior
118+
change for them? If so, how are you going to minimize the disruption
119+
to existing users?
120+
-->
121+
122+
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.
123+
124+
## Alternatives
125+
126+
<!--
127+
What other designs did you consider? Why did you decide against those?
128+
129+
This section should also include prior art, such as whether similar
130+
projects have already implemented a similar feature.
131+
-->
132+
133+
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.
134+
> [TypeScript compiler options](https://www.typescriptlang.org/docs/handbook/compiler-options.html#compiler-options)
135+
> https://github.com/eslint/eslint/issues/9870#issuecomment-359228967
136+
137+
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.
138+
139+
2. Is it possible to check `@locale/module` in the same way as `@type/module`?
140+
141+
## Open Questions
142+
143+
<!--
144+
This section is optional, but is suggested for a first draft.
145+
146+
What parts of this proposal are you unclear about? What do you
147+
need to know before you can finalize this RFC?
148+
149+
List the questions that you'd like reviewers to focus on. When
150+
you've received the answers and updated the design to reflect them,
151+
you can remove this section.
152+
-->
153+
154+
## Help Needed
155+
156+
<!--
157+
This section is optional.
158+
159+
Are you able to implement this RFC on your own? If not, what kind
160+
of help would you need from the team?
161+
-->
162+
163+
I sure I can implement this RFC on my own.
164+
165+
## Frequently Asked Questions
166+
167+
<!--
168+
This section is optional but suggested.
169+
170+
Try to anticipate points of clarification that might be needed by
171+
the people reviewing this RFC. Include those questions and answers
172+
in this section.
173+
-->
174+
175+
## Related Discussions
176+
177+
<!--
178+
This section is optional but suggested.
179+
180+
If there is an issue, pull request, or other URL that provides useful
181+
context for this proposal, please include those links here.
182+
-->
183+
184+
- https://github.com/eslint/eslint/issues/19210
185+
- https://github.com/eslint/eslint/issues/9870

0 commit comments

Comments
 (0)