An open source design system that's fully customizable and agent ready
TypeScript
feat(eslint): add @astryx/no-hardcoded-i18n-string rule (#4010)
nynexman4464dd1d6555d5eb
diff --git a/.changeset/i18n-no-hardcoded-string-lint.md b/.changeset/i18n-no-hardcoded-string-lint.mdnew file mode 100644index 0000000000..723c32afcc--- /dev/null+++ b/.changeset/i18n-no-hardcoded-string-lint.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[feat] New ESLint rule `@astryx/no-hardcoded-i18n-string` (in `@astryx/eslint-plugin-astryx`, `astryx.configs.strict` / `astryx.configs.recommended`). Flags hardcoded English string literals on user-facing props so future component work can't skip translation. The rule is filesystem-agnostic — downstream packages that ship translatable UI can enable it in their own ESLint config with the standard `files` / `ignores` pattern.++@nynexman4464diff --git a/eslint.config.js b/eslint.config.jsindex 81d5c32809..13d8ebce39 100644--- a/eslint.config.js+++ b/eslint.config.js@@ -176,6 +176,15 @@ export default defineConfig(}],},},+ // The i18n runtime itself defines the message strings the rest of the+ // package resolves against; a "hardcoded string" check against it would be+ // circular. Turn off @astryx/no-hardcoded-i18n-string just for this dir.+ {+ files: ["packages/core/src/i18n/**/*.{ts,tsx}"],+ rules: {+ '@astryx/no-hardcoded-i18n-string': 'off',+ },+ },// React bug-prevention rules - applies to core package// Uses @eslint-react for bugs that TypeScript alone cannot catch.// Children.*/cloneElement are already covered by @astryx/no-react-introspection.diff --git a/internal/eslint-plugin-astryx/index.js b/internal/eslint-plugin-astryx/index.jsindex 86e0137ed7..bf85368503 100644--- a/internal/eslint-plugin-astryx/index.js+++ b/internal/eslint-plugin-astryx/index.js@@ -29,6 +29,7 @@ import copyrightHeaderRule from './copyright-header.js';import noRawConsoleCliRule from './no-raw-console-cli.js';import requireBasePropsRule from './require-base-props.js';import requireRefPropRule from './require-ref-prop.js';+import noHardcodedI18nStringRule from './no-hardcoded-i18n-string.js';// =============================================================================// Rule: no-hardcoded-styles@@ -243,6 +244,7 @@ const plugin = {'require-ref-prop': requireRefPropRule,'copyright-header': copyrightHeaderRule,'no-raw-console-cli': noRawConsoleCliRule,+ 'no-hardcoded-i18n-string': noHardcodedI18nStringRule,},configs: {},};@@ -267,6 +269,7 @@ plugin.configs.strict = {'@astryx/require-base-props': 'error','@astryx/require-ref-prop': 'error','@astryx/copyright-header': 'error',+ '@astryx/no-hardcoded-i18n-string': 'error',},};@@ -290,6 +293,7 @@ plugin.configs.recommended = {'@astryx/require-base-props': 'warn','@astryx/require-ref-prop': 'warn','@astryx/copyright-header': 'error',+ '@astryx/no-hardcoded-i18n-string': 'warn',},};diff --git a/internal/eslint-plugin-astryx/no-hardcoded-i18n-string.js b/internal/eslint-plugin-astryx/no-hardcoded-i18n-string.jsnew file mode 100644index 0000000000..1ac85be369--- /dev/null+++ b/internal/eslint-plugin-astryx/no-hardcoded-i18n-string.js@@ -0,0 +1,264 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file no-hardcoded-i18n-string.js+ * @description Disallow hardcoded English string literals in user-facing+ * props. Any package that ships translatable UI can enable this rule; scope+ * it with the standard flat-config `files: [...]` pattern.+ *+ * The rule itself is filesystem-agnostic — it does not hardcode any path.+ * The caller decides where to run it via `files` / `ignores` in the ESLint+ * config, and where the i18n runtime itself lives via `ignores`.+ *+ * Flags:+ * 1. JSX attributes named like *Label / *Text / *Placeholder / *Title+ * / *Message / *Tooltip / *Hint / *Description / *Summary, plus+ * `label`, `placeholder`, `title`, `tooltip`, `text`, `summary`,+ * `message`, `description`, `hint`, and the specific `aria-*`+ * attributes that take user-visible text (`aria-label`,+ * `aria-description`, `aria-placeholder`, `aria-roledescription`,+ * `aria-valuetext`, `aria-braillelabel`, `aria-brailleroledescription`,+ * `aria-keyshortcuts`), when the value is a hardcoded string literal+ * that "looks user-facing". Other `aria-*` attributes (aria-controls,+ * aria-expanded, aria-hidden, …) take IDs / booleans / enums and are+ * NOT flagged.+ * 2. Object property assignments of the same names inside .tsx files.+ * 3. Destructure defaults (`function Foo({label = 'X'})`) of the same names.+ *+ * Ignores:+ * - Test files (*.test.*, __tests__/**)+ * - Storybook stories (*.stories.*)+ * - Doc files (*.doc.mjs)+ * - JSDoc @example blocks (comments)+ * - Values that look non-user-facing (lowercase identifier-only, empty, etc.)+ *+ * Good:+ * <button aria-label={t('foo.label')}>+ * {label: t('powersearch.operator.contains')}+ * function Foo({label: labelFromProps}) {+ * const label = labelFromProps ?? t('foo.label');+ * }+ *+ * Bad:+ * <button aria-label="Close">+ * {key: 'contains', label: 'contains'}+ * function Foo({label = 'Cancel'})+ */++/**+ * Attribute / property names that we consider user-facing text sinks.+ * Exact matches AND suffix-match patterns.+ */+const EXACT_NAMES = new Set([+ 'label',+ 'placeholder',+ 'title',+ 'tooltip',+ 'text',+ 'summary',+ 'message',+ 'description',+ 'hint',+]);++/**+ * `aria-*` attributes whose values are user-visible text per WAI-ARIA 1.3.+ * All other aria-* attributes take IDs, booleans, tristates, integers, or+ * enum tokens — not translatable prose — so we deliberately do NOT flag them.+ */+const ARIA_TEXT_ATTRS = new Set([+ 'aria-label',+ 'aria-description',+ 'aria-placeholder',+ 'aria-roledescription',+ 'aria-valuetext',+ 'aria-braillelabel',+ 'aria-brailleroledescription',+ // Note: aria-keyshortcuts contains keyboard key names ("Alt+Shift+P"); those+ // are typically NOT translated (key names are usually a locale/OS concern+ // handled by the platform), but consumers who DO want to localize should+ // still route them through i18n — we include it to prevent hardcoded English+ // key hints from slipping in.+ 'aria-keyshortcuts',+]);++/**+ * Suffix patterns for user-facing prop names. Any prop name ending in+ * one of these is flagged.+ */+const SUFFIX_PATTERNS = [+ /Label$/, // saveButtonLabel, cancelLabel, previousLabel, ...+ /Text$/, // emptySearchText, helperText, errorText, ...+ /Placeholder$/,// searchPlaceholder, timePlaceholder, ...+ /Title$/, // dialogTitle, ...+ /Message$/, // disabledMessage, errorMessage, ...+ /Tooltip$/, // ...+ /Hint$/, // ...+ /Description$/,// ...+ /Summary$/, // ...+];++function isUserFacingName(name) {+ if (typeof name !== 'string') return false;+ if (EXACT_NAMES.has(name)) return true;+ if (ARIA_TEXT_ATTRS.has(name)) return true;+ for (const pat of SUFFIX_PATTERNS) {+ if (pat.test(name)) return true;+ }+ return false;+}++/**+ * Heuristic — does this string LOOK like user-facing English?+ * - Non-empty, longer than 1 char.+ * - Starts with a capital, OR contains a space, OR ends with punctuation.+ * - Not obviously an identifier (single lowercase word, all-caps constant).+ * - Not a URL, path, or data: URI.+ */+function looksUserFacing(value) {+ if (typeof value !== 'string') return false;+ if (value.length < 2) return false;+ if (value.length > 200) return false; // probably not a UI label+ // URL / path / data+ if (+ value.startsWith('/') ||+ value.startsWith('http') ||+ value.startsWith('data:') ||+ value.startsWith('#') ||+ value.startsWith('.')+ ) {+ return false;+ }+ // All-caps enum constant like `IS_ANY_OF`+ if (value === value.toUpperCase() && /[A-Z_]/.test(value) && !/\s/.test(value)) {+ return false;+ }+ // Single lowercase word (identifier-shaped: `contains`, `email`, `foo123`)+ if (/^[a-z][a-z0-9]*$/.test(value)) return false;+ // Has a space, OR starts with uppercase, OR ends with ., …, !, ?+ const hasSpace = /\s/.test(value);+ const startsUpper = /^[A-Z]/.test(value);+ const endsWithPunct = /[.…!?]$/.test(value);+ return hasSpace || startsUpper || endsWithPunct;+}++const IGNORED_FILE_PATTERNS = [+ /\.test\./,+ /\.stories\./,+ /\.doc\.mjs$/,+ /__tests__/,+ /\.perf\.test\./,+];++function shouldIgnoreFile(filename) {+ return IGNORED_FILE_PATTERNS.some(p => p.test(filename));+}++const rule = {+ meta: {+ type: 'problem',+ docs: {+ description:+ 'Disallow hardcoded user-facing strings; route through useTranslator() instead',+ category: 'Best Practices',+ recommended: true,+ },+ messages: {+ hardcodedString:+ 'Hardcoded user-facing string {{value}} in `{{name}}`. ' ++ 'Route through `t(\'<namespace>.<component>.<key>\')` via `useTranslator()` so it can be localized.',+ hardcodedDefault:+ 'Hardcoded default {{value}} for prop `{{name}}`. ' ++ 'Use the alias-and-resolve pattern: `{{name}}: {{name}}FromProps` in the destructure, then ' ++ '`const {{name}} = {{name}}FromProps ?? t(\'<namespace>.<component>.<key>\');` inside the body.',+ },+ schema: [],+ },+ create(context) {+ const filename = context.filename;+ if (shouldIgnoreFile(filename)) return {};++ return {+ // 1. JSX attribute string literals: <X label="Cancel">+ JSXAttribute(node) {+ if (!node.name || node.name.type === 'JSXNamespacedName') return;+ const name =+ node.name.type === 'JSXIdentifier'+ ? node.name.name+ : null;+ if (!isUserFacingName(name)) return;+ // Attribute value must be a string literal (not a JSX expression)+ if (+ node.value?.type !== 'Literal' ||+ typeof node.value.value !== 'string'+ )+ return;+ const val = node.value.value;+ if (!looksUserFacing(val)) return;+ context.report({+ node: node.value,+ messageId: 'hardcodedString',+ data: {value: JSON.stringify(val), name},+ });+ },++ // 2. Object property `label: 'Xxx'`+ Property(node) {+ if (node.computed || node.shorthand) return;+ const name =+ node.key.type === 'Identifier'+ ? node.key.name+ : node.key.type === 'Literal'+ ? node.key.value+ : null;+ if (!isUserFacingName(name)) return;+ if (+ node.value.type !== 'Literal' ||+ typeof node.value.value !== 'string'+ )+ return;+ const val = node.value.value;+ if (!looksUserFacing(val)) return;+ context.report({+ node: node.value,+ messageId: 'hardcodedString',+ data: {value: JSON.stringify(val), name},+ });+ },++ // 3. Destructure default: `function Foo({label = 'X'} : Props)`+ // ObjectPattern > Property with a shorthand-alike `key = default` pattern.+ // In AST that's an AssignmentPattern whose parent is a Property in an ObjectPattern.+ AssignmentPattern(node) {+ // Only when we're the value of a Property inside an ObjectPattern+ if (+ node.parent?.type !== 'Property' ||+ node.parent.parent?.type !== 'ObjectPattern'+ )+ return;+ const property = node.parent;+ const name =+ property.key.type === 'Identifier'+ ? property.key.name+ : property.key.type === 'Literal'+ ? property.key.value+ : null;+ if (!isUserFacingName(name)) return;+ if (+ node.right.type !== 'Literal' ||+ typeof node.right.value !== 'string'+ )+ return;+ const val = node.right.value;+ if (!looksUserFacing(val)) return;+ context.report({+ node: node.right,+ messageId: 'hardcodedDefault',+ data: {value: JSON.stringify(val), name},+ });+ },+ };+ },+};++export default rule;