Skip to content

The open alternative to Salesforce, designed for AI.

Restore code identifiers the docs translated into prose (#25858)

Félix Malfait247ff6ecbda4
diff --git a/packages/twenty-utils/crowdin-normalizer/constants/__tests__/normalization-rules.constant.spec.ts b/packages/twenty-utils/crowdin-normalizer/constants/__tests__/normalization-rules.constant.spec.ts
index 4e1844ee095..a9f74fb39e4 100644
--- a/packages/twenty-utils/crowdin-normalizer/constants/__tests__/normalization-rules.constant.spec.ts
+++ b/packages/twenty-utils/crowdin-normalizer/constants/__tests__/normalization-rules.constant.spec.ts
@@ -19,10 +19,22 @@ describe('NORMALIZATION_RULES', () => {
});
it('keeps the ICU rules away from MDX, where braces are JSX', () => {
- expect(namesFor('mdx')).toEqual(['escaped-inline-code-tags']);
+ expect(namesFor('mdx')).toEqual([
+ 'escaped-inline-code-tags',
+ 'translated-identifier',
+ ]);
});
- it('runs every rule against PO catalogs', () => {
- expect(namesFor('po')).toHaveLength(NORMALIZATION_RULES.length);
+ // Identifiers, links and code spans are an MDX concern; every other rule
+ // reads an ICU catalog and belongs to PO.
+ it('runs every rule but the MDX-specific one against PO catalogs', () => {
+ const mdxOnly = NORMALIZATION_RULES.filter(
+ (rule) => !rule.formats.includes('po'),
+ ).map((rule) => rule.name);
+
+ expect(mdxOnly).toEqual(['translated-identifier']);
+ expect(namesFor('po')).toHaveLength(
+ NORMALIZATION_RULES.length - mdxOnly.length,
+ );
});
});
diff --git a/packages/twenty-utils/crowdin-normalizer/constants/normalization-rules.constant.ts b/packages/twenty-utils/crowdin-normalizer/constants/normalization-rules.constant.ts
index 25c95ca9773..3f693b9801b 100644
--- a/packages/twenty-utils/crowdin-normalizer/constants/normalization-rules.constant.ts
+++ b/packages/twenty-utils/crowdin-normalizer/constants/normalization-rules.constant.ts
@@ -3,6 +3,7 @@ import { ESCAPED_INLINE_CODE_TAGS_RULE } from '../rules/escaped-inline-code-tags
import { ESCAPED_UNICODE_RULE } from '../rules/escaped-unicode.rule';
import { INVENTED_ARGUMENT_RULE } from '../rules/invented-argument.rule';
import { INVENTED_MARKUP_RULE } from '../rules/invented-markup.rule';
+import { TRANSLATED_IDENTIFIER_RULE } from '../rules/translated-identifier.rule';
import { WORDLESS_TRANSLATION_RULE } from '../rules/wordless-translation.rule';
import { type NormalizationRule } from '../types/normalization-rule.type';
@@ -13,4 +14,5 @@ export const NORMALIZATION_RULES: NormalizationRule[] = [
INVENTED_MARKUP_RULE,
INVENTED_ARGUMENT_RULE,
WORDLESS_TRANSLATION_RULE,
+ TRANSLATED_IDENTIFIER_RULE,
];
diff --git a/packages/twenty-utils/crowdin-normalizer/rules/__tests__/translated-identifier.rule.spec.ts b/packages/twenty-utils/crowdin-normalizer/rules/__tests__/translated-identifier.rule.spec.ts
new file mode 100644
index 00000000000..9c8cc862eed
--- /dev/null
+++ b/packages/twenty-utils/crowdin-normalizer/rules/__tests__/translated-identifier.rule.spec.ts
@@ -0,0 +1,126 @@
+import { TRANSLATED_IDENTIFIER_RULE } from '../translated-identifier.rule';
+
+const { detect, fix } = TRANSLATED_IDENTIFIER_RULE;
+
+describe('TRANSLATED_IDENTIFIER_RULE', () => {
+ it('restores a code identifier translated inside backticks', () => {
+ const sourceText =
+ 'Re-renders are often caused by unnecessary `useEffect`.';
+ const translationText =
+ 'وكثيرا ما تكون عمليات إعادة التسليم ناجمة عن `فعالية الاستخدام` غير الضرورية.';
+
+ expect(detect(translationText, sourceText)).toBe(true);
+ expect(fix(translationText, sourceText)).toBe(
+ 'وكثيرا ما تكون عمليات إعادة التسليم ناجمة عن `useEffect` غير الضرورية.',
+ );
+ });
+
+ // A translation reorders spans to suit its own grammar, so position says
+ // nothing about which source span belongs in which slot.
+ it('stands down on more than one span, where order cannot be trusted', () => {
+ const sourceText =
+ 'The `twenty-app` keyword in your `package.json` `keywords` array';
+ const translationText =
+ 'Cuvântul cheie `twenty-app` din array-ul `keywords` al fișierului `package.json`';
+
+ expect(detect(translationText, sourceText)).toBe(false);
+ expect(fix(translationText, sourceText)).toBe(translationText);
+ });
+
+ // Backticks in the docs mark UI labels as often as symbols, and the reader
+ // sees those labels translated in their own app, so restoring them would
+ // un-translate correct work.
+ it.each([
+ [
+ 'Go to `Settings` in the left sidebar.',
+ 'Accesați `Setări` din bara laterală stângă.',
+ ],
+ [
+ 'Go to `Data Model`, then select the object.',
+ 'Accesați `Model de date`, apoi selectați obiectul.',
+ ],
+ [
+ 'Select `Deactivate` from the dropdown.',
+ 'Selectați `Dezactivează` din lista derulantă.',
+ ],
+ ])('keeps a translated UI label: %s', (sourceText, translationText) => {
+ expect(detect(translationText, sourceText)).toBe(false);
+ expect(fix(translationText, sourceText)).toBe(translationText);
+ });
+
+ it.each([
+ [
+ 'Caused by `useEffect`.',
+ 'Cauzat de `efectul de utilizare`.',
+ 'Cauzat de `useEffect`.',
+ ],
+ [
+ 'Fields of type `SELECT`.',
+ 'Câmpuri de tip `SELECTARE`.',
+ 'Câmpuri de tip `SELECT`.',
+ ],
+ [
+ 'Set `is_auth_required`.',
+ 'Setați `este_necesară_autentificarea`.',
+ 'Setați `is_auth_required`.',
+ ],
+ [
+ 'Call `client.run()`.',
+ 'Apelați `client.rulează()`.',
+ 'Apelați `client.run()`.',
+ ],
+ [
+ 'Build the `twenty-emails` package first.',
+ 'Vous devez construire le paquet `vingt-emails`.',
+ 'Vous devez construire le paquet `twenty-emails`.',
+ ],
+ [
+ 'Send the `x-slack-signature` header.',
+ 'Trimiteți antetul `x-semnătură-slack`.',
+ 'Trimiteți antetul `x-slack-signature`.',
+ ],
+ ])(
+ 'restores an identifier-shaped span: %s',
+ (sourceText, translationText, expected) => {
+ expect(detect(translationText, sourceText)).toBe(true);
+ expect(fix(translationText, sourceText)).toBe(expected);
+ },
+ );
+
+ // Lining them up positionally is only sound when both sides hold the same
+ // number; a translation that dropped or added one cannot be matched safely.
+ it('stands down when the counts do not line up', () => {
+ const sourceText = 'Use `a` and `b`.';
+
+ expect(detect('Utilisez `x`.', sourceText)).toBe(false);
+ expect(fix('Utilisez `x`.', sourceText)).toBe('Utilisez `x`.');
+ });
+
+ it('leaves a translation whose identifiers already match', () => {
+ const sourceText = 'Call `useEffect` from [here](/docs/a).';
+ const translationText = 'Appelez `useEffect` depuis [ici](/docs/a).';
+
+ expect(detect(translationText, sourceText)).toBe(false);
+ });
+
+ // Translated pages live under /l/<lang>/ and link to each other there, so a
+ // locale-prefixed target is the translation being right, not wrong. Paths and
+ // link targets are left to a human.
+ it('leaves link targets alone, including locale-prefixed ones', () => {
+ const sourceText = 'See [the guide](/user-guide/billing).';
+ const translationText = 'Vezi [ghidul](/l/ro/user-guide/billing).';
+
+ expect(detect(translationText, sourceText)).toBe(false);
+ expect(fix(translationText, sourceText)).toBe(translationText);
+ });
+
+ it('stands down when the source is unknown', () => {
+ expect(detect('`useEffect`', undefined)).toBe(false);
+ expect(fix('`useEffect`', undefined)).toBe('`useEffect`');
+ });
+
+ it('runs against MDX catalogs only', () => {
+ expect(TRANSLATED_IDENTIFIER_RULE.formats).toEqual(['mdx']);
+ expect(TRANSLATED_IDENTIFIER_RULE.needsSourceText).toBe(true);
+ });
+});
diff --git a/packages/twenty-utils/crowdin-normalizer/rules/translated-identifier.rule.ts b/packages/twenty-utils/crowdin-normalizer/rules/translated-identifier.rule.ts
new file mode 100644
index 00000000000..50f552265f2
--- /dev/null
+++ b/packages/twenty-utils/crowdin-normalizer/rules/translated-identifier.rule.ts
@@ -0,0 +1,70 @@
+import { type NormalizationRule } from '../types/normalization-rule.type';
+
+// Backticks in the docs carry two different things: symbols the machine
+// resolves, and UI labels the reader sees translated in their own app. Only the
+// first kind is restored - a span shaped like an identifier, never one shaped
+// like prose - so `useEffect` and `SELECT` are put back while `Settings` and
+// `Data Model` stay in the reader's language.
+const INLINE_CODE_REGEX = /`[^`\n]+`/g;
+
+function codeSpansIn(text: string): string[] {
+ return [...text.matchAll(new RegExp(INLINE_CODE_REGEX))].map(
+ ([match]) => match,
+ );
+}
+
+// Package, command and header names are hyphenated lowercase, and that is the
+// shape translators actually broke: the French docs ship `vingt-emails` and the
+// Japanese `20-emails` for `twenty-emails`, each inside an npx command nobody
+// can run. Nothing in the English source has this shape without being a symbol.
+const KEBAB_CASE_REGEX = /^[a-z0-9]+(?:-[a-z0-9]+)+$/;
+
+function looksLikeIdentifier(span: string): boolean {
+ const code = span.slice(1, -1);
+
+ if (/\s/.test(code)) return false;
+
+ return (
+ /[a-z][A-Z]/.test(code) ||
+ /[_./(]/.test(code) ||
+ /^[A-Z0-9_]+$/.test(code) ||
+ KEBAB_CASE_REGEX.test(code)
+ );
+}
+
+// Only a message carrying exactly one span on each side is repaired. Lining
+// spans up by position looked obvious and is wrong: a translation reorders them
+// to suit its own grammar, so "the `twenty-app` keyword in your `package.json`
+// `keywords` array" comes back with keywords and package.json swapped, and
+// restoring by position writes package.json over both. With one span there is
+// no order to get wrong.
+function restoreIdentifiers(text: string, sourceText?: string): string {
+ if (sourceText === undefined) return text;
+
+ const sourceSpans = codeSpansIn(sourceText);
+ const targetSpans = codeSpansIn(text);
+
+ if (
+ sourceSpans.length !== 1 ||
+ targetSpans.length !== 1 ||
+ !looksLikeIdentifier(sourceSpans[0])
+ ) {
+ return text;
+ }
+
+ return text.replace(INLINE_CODE_REGEX, sourceSpans[0]);
+}
+
+function hasTranslatedIdentifier(text: string, sourceText?: string): boolean {
+ if (sourceText === undefined) return false;
+
+ return restoreIdentifiers(text, sourceText) !== text;
+}
+
+export const TRANSLATED_IDENTIFIER_RULE: NormalizationRule = {
+ name: 'translated-identifier',
+ formats: ['mdx'],
+ needsSourceText: true,
+ detect: hasTranslatedIdentifier,
+ fix: restoreIdentifiers,
+};