Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(eslint): add @astryx/i18n-key-format rule (#4015)

nynexman4464eb549c88a8bc
diff --git a/.changeset/i18n-key-format-lint.md b/.changeset/i18n-key-format-lint.md
new file mode 100644
index 0000000000..18d41f02e6
--- /dev/null
+++ b/.changeset/i18n-key-format-lint.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] New ESLint rule `@astryx/i18n-key-format` (in `@astryx/eslint-plugin-astryx`, `astryx.configs.strict` / `astryx.configs.recommended`). Enforces camelCase path segments for `@astryx.*` catalog keys — matches how astryx already ships every key and prevents future drift.
+
+@nynexman4464
diff --git a/internal/eslint-plugin-astryx/i18n-key-format.js b/internal/eslint-plugin-astryx/i18n-key-format.js
new file mode 100644
index 0000000000..9a44407a59
--- /dev/null
+++ b/internal/eslint-plugin-astryx/i18n-key-format.js
@@ -0,0 +1,184 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file i18n-key-format.js
+ * @description Enforce catalog-key naming conventions for
+ * `t('@astryx.<path>')` calls and `i18nKey: '@astryx.<path>'` config
+ * fields. Complements `no-hardcoded-i18n-string`: the sibling rule
+ * enforces WHERE strings go (through the catalog), and this rule
+ * enforces WHAT the catalog keys look like.
+ *
+ * Astryx catalog keys are dot-separated paths under the `@astryx.`
+ * namespace, e.g. `@astryx.pagination.next` or
+ * `@astryx.powersearch.operator.isAnyOf`. Every path segment must be
+ * camelCase — no snake_case, no PascalCase, no kebab-case. camelCase
+ * is the ecosystem-dominant convention (React Aria, MUI X, Ant Design,
+ * Ark UI all camelCase) and matches JS identifier conventions so the
+ * key body can lift straight into a props / config field name.
+ *
+ * The rule flags:
+ *
+ * 1. Astryx-namespaced string literal arguments to any `t(...)` /
+ * `translator(...)` / `useTranslator()(...)` call.
+ * 2. Astryx-namespaced string literal values assigned to an
+ * `i18nKey` property.
+ *
+ * Only `@astryx.` keys are checked — third-party namespaces are left
+ * to their owners to enforce.
+ *
+ * Good:
+ * t('@astryx.pagination.next')
+ * t('@astryx.powersearch.operator.isAnyOf')
+ * {key: 'is_any_of', i18nKey: '@astryx.powersearch.operator.isAnyOf'}
+ *
+ * Bad:
+ * t('@astryx.pagination.NEXT') // SCREAMING is not camelCase
+ * t('@astryx.power_search.operator') // snake_case segment
+ * t('@astryx.PowerSearch.operator') // PascalCase segment
+ * t('@astryx.power-search.operator') // kebab-case segment
+ * t('astryx.pagination.next') // missing @ prefix — resolver
+ * // looks up '@astryx.<key>'
+ * // literally so this misses.
+ * t('@astryx.pagination') // no leaf key (must be
+ * // @astryx.<component>.<key>+)
+ */
+
+const ASTRYX_KEY_PATTERN = /^@astryx\.[^ ]+$/;
+
+/**
+ * A path segment is camelCase when it:
+ * - starts with a lowercase letter
+ * - contains only letters and digits (no `_`, `-`, no whitespace)
+ * - is not entirely uppercase (`URL` is fine as a suffix but `URL` on
+ * its own would fail the lowercase-start check anyway)
+ */
+const CAMEL_CASE_SEGMENT = /^[a-z][a-zA-Z0-9]*$/;
+
+/**
+ * Check if a full astryx catalog key is well-formed.
+ * Returns { ok: true } or { ok: false, reason: string }.
+ */
+function checkKey(key) {
+ if (!ASTRYX_KEY_PATTERN.test(key)) {
+ return {
+ ok: false,
+ reason:
+ 'Astryx catalog keys must match `@astryx.<segment>(.<segment>)+` with no whitespace.',
+ };
+ }
+ const segments = key.slice('@astryx.'.length).split('.');
+ if (segments.length < 2) {
+ return {
+ ok: false,
+ reason:
+ 'Astryx catalog keys need at least two segments after `@astryx.` (component + leaf, e.g. `@astryx.pagination.next`).',
+ };
+ }
+ for (const segment of segments) {
+ if (!segment) {
+ return {ok: false, reason: 'Empty path segment (double dot?).'};
+ }
+ if (!CAMEL_CASE_SEGMENT.test(segment)) {
+ return {
+ ok: false,
+ reason: `Path segment \`${segment}\` is not camelCase. Use \`camelCase\` — no snake_case, PascalCase, or kebab-case.`,
+ };
+ }
+ }
+ return {ok: true};
+}
+
+/** Names of translator functions we recognize as call targets. */
+const TRANSLATOR_CALL_NAMES = new Set(['t', 'translator', 'translate']);
+
+function isTranslatorCall(node) {
+ // Direct: t('@astryx.foo.bar')
+ if (node.callee.type === 'Identifier') {
+ return TRANSLATOR_CALL_NAMES.has(node.callee.name);
+ }
+ // Member: some.thing.t('...') — check the final property
+ if (
+ node.callee.type === 'MemberExpression' &&
+ !node.callee.computed &&
+ node.callee.property.type === 'Identifier'
+ ) {
+ return TRANSLATOR_CALL_NAMES.has(node.callee.property.name);
+ }
+ return false;
+}
+
+function getStringArg(node) {
+ const first = node.arguments[0];
+ if (!first) return null;
+ if (first.type === 'Literal' && typeof first.value === 'string') {
+ return {value: first.value, node: first};
+ }
+ return null;
+}
+
+const rule = {
+ meta: {
+ type: 'problem',
+ docs: {
+ description:
+ 'Enforce camelCase path segments for @astryx.* i18n catalog keys',
+ category: 'Best Practices',
+ recommended: true,
+ },
+ messages: {
+ badKey: 'Malformed astryx catalog key {{key}}. {{reason}}',
+ },
+ schema: [],
+ },
+ create(context) {
+ function reportIfBad(strValue, node) {
+ // Enforce anything that clearly targets the astryx namespace — with
+ // or without the `@` prefix. A missing `@` is a real bug (the
+ // runtime resolver looks up `@astryx.<key>` literally); silently
+ // skipping the check means the string routes through the catalog
+ // but never hits a key. Third-party namespaces (`@myapp.*`,
+ // `@company.*`) are still their owner's concern; we only recognize
+ // astryx.
+ const isAstryxKey =
+ strValue.startsWith('@astryx.') || strValue.startsWith('astryx.');
+ if (!isAstryxKey) return;
+ const result = checkKey(strValue);
+ if (result.ok) return;
+ context.report({
+ node,
+ messageId: 'badKey',
+ data: {key: JSON.stringify(strValue), reason: result.reason},
+ });
+ }
+
+ return {
+ // 1. t('@astryx.foo.bar') / translator('@astryx.foo.bar')
+ CallExpression(node) {
+ if (!isTranslatorCall(node)) return;
+ const arg = getStringArg(node);
+ if (arg === null) return;
+ reportIfBad(arg.value, arg.node);
+ },
+
+ // 2. Object property `i18nKey: '@astryx.foo.bar'`
+ 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 (name !== 'i18nKey') return;
+ if (
+ node.value.type !== 'Literal' ||
+ typeof node.value.value !== 'string'
+ )
+ return;
+ reportIfBad(node.value.value, node.value);
+ },
+ };
+ },
+};
+
+export default rule;
diff --git a/internal/eslint-plugin-astryx/index.js b/internal/eslint-plugin-astryx/index.js
index bf85368503..2b9cb2184b 100644
--- a/internal/eslint-plugin-astryx/index.js
+++ b/internal/eslint-plugin-astryx/index.js
@@ -30,6 +30,7 @@ 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';
+import i18nKeyFormatRule from './i18n-key-format.js';
// =============================================================================
// Rule: no-hardcoded-styles
@@ -245,6 +246,7 @@ const plugin = {
'copyright-header': copyrightHeaderRule,
'no-raw-console-cli': noRawConsoleCliRule,
'no-hardcoded-i18n-string': noHardcodedI18nStringRule,
+ 'i18n-key-format': i18nKeyFormatRule,
},
configs: {},
};
@@ -270,6 +272,7 @@ plugin.configs.strict = {
'@astryx/require-ref-prop': 'error',
'@astryx/copyright-header': 'error',
'@astryx/no-hardcoded-i18n-string': 'error',
+ '@astryx/i18n-key-format': 'error',
},
};
@@ -294,6 +297,7 @@ plugin.configs.recommended = {
'@astryx/require-ref-prop': 'warn',
'@astryx/copyright-header': 'error',
'@astryx/no-hardcoded-i18n-string': 'warn',
+ '@astryx/i18n-key-format': 'warn',
},
};