@alauda/doom 2.5.4 → 2.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (92) hide show
  1. package/lib/cli/api.d.ts +2 -0
  2. package/lib/cli/api.js +147 -0
  3. package/lib/cli/helpers.d.ts +1 -7
  4. package/lib/cli/helpers.js +4 -41
  5. package/lib/cli/index.js +2 -0
  6. package/lib/cli/translate-agent.d.ts +81 -0
  7. package/lib/cli/translate-agent.js +450 -0
  8. package/lib/cli/translate-check.d.ts +17 -0
  9. package/lib/cli/translate-check.js +67 -0
  10. package/lib/cli/translate-checker.d.ts +58 -0
  11. package/lib/cli/translate-checker.js +112 -0
  12. package/lib/cli/translate-judge.d.ts +119 -0
  13. package/lib/cli/translate-judge.js +224 -0
  14. package/lib/cli/translate-limits.d.ts +43 -0
  15. package/lib/cli/translate-limits.js +55 -0
  16. package/lib/cli/translate-mask.d.ts +144 -0
  17. package/lib/cli/translate-mask.js +617 -0
  18. package/lib/cli/translate-models.d.ts +127 -0
  19. package/lib/cli/translate-models.js +189 -0
  20. package/lib/cli/translate-scratch.d.ts +142 -0
  21. package/lib/cli/translate-scratch.js +187 -0
  22. package/lib/cli/translate-terms.d.ts +22 -0
  23. package/lib/cli/translate-terms.js +33 -0
  24. package/lib/cli/translate.d.ts +15 -10
  25. package/lib/cli/translate.js +228 -185
  26. package/lib/eslint.js +22 -3
  27. package/lib/plugins/api/index.js +1 -1
  28. package/lib/plugins/api/types.d.ts +36 -1
  29. package/lib/plugins/global/components.d.ts +16 -0
  30. package/lib/plugins/global/components.js +16 -1
  31. package/lib/remark-lint/index.d.ts +20 -0
  32. package/lib/remark-lint/index.js +40 -0
  33. package/lib/remark-lint/no-unmatched-anchor.d.ts +10 -0
  34. package/lib/remark-lint/no-unmatched-anchor.js +13 -0
  35. package/lib/remark-lint/no-unopened-frontmatter.d.ts +2 -0
  36. package/lib/remark-lint/no-unopened-frontmatter.js +70 -0
  37. package/lib/remark-lint/no-unparsed-emphasis.d.ts +2 -0
  38. package/lib/remark-lint/no-unparsed-emphasis.js +53 -0
  39. package/lib/remark-lint/no-unresolved-api-ref.d.ts +40 -0
  40. package/lib/remark-lint/no-unresolved-api-ref.js +194 -0
  41. package/lib/remark-lint/rule-sets.d.ts +75 -0
  42. package/lib/remark-lint/rule-sets.js +120 -0
  43. package/lib/remark-lint/translation-parity/component-multiset.d.ts +17 -0
  44. package/lib/remark-lint/translation-parity/component-multiset.js +35 -0
  45. package/lib/remark-lint/translation-parity/echoed-source.d.ts +2 -0
  46. package/lib/remark-lint/translation-parity/echoed-source.js +37 -0
  47. package/lib/remark-lint/translation-parity/frontmatter-preservation.d.ts +2 -0
  48. package/lib/remark-lint/translation-parity/frontmatter-preservation.js +36 -0
  49. package/lib/remark-lint/translation-parity/heading-sequence.d.ts +12 -0
  50. package/lib/remark-lint/translation-parity/heading-sequence.js +25 -0
  51. package/lib/remark-lint/translation-parity/index.d.ts +24 -0
  52. package/lib/remark-lint/translation-parity/index.js +24 -0
  53. package/lib/remark-lint/translation-parity/jsx-attribute-parity.d.ts +14 -0
  54. package/lib/remark-lint/translation-parity/jsx-attribute-parity.js +47 -0
  55. package/lib/remark-lint/translation-parity/length-ratio.d.ts +2 -0
  56. package/lib/remark-lint/translation-parity/length-ratio.js +49 -0
  57. package/lib/remark-lint/translation-parity/link-isomorphism.d.ts +26 -0
  58. package/lib/remark-lint/translation-parity/link-isomorphism.js +45 -0
  59. package/lib/remark-lint/translation-parity/shared.d.ts +110 -0
  60. package/lib/remark-lint/translation-parity/shared.js +282 -0
  61. package/lib/remark-lint/translation-parity/terminology-adherence.d.ts +2 -0
  62. package/lib/remark-lint/translation-parity/terminology-adherence.js +67 -0
  63. package/lib/remark-lint/translation-parity/up-to-date.d.ts +11 -0
  64. package/lib/remark-lint/translation-parity/up-to-date.js +21 -0
  65. package/lib/remark-lint/translation-parity/url-residue.d.ts +2 -0
  66. package/lib/remark-lint/translation-parity/url-residue.js +46 -0
  67. package/lib/remarkrc.d.ts +1 -1
  68. package/lib/remarkrc.js +7 -34
  69. package/lib/runtime/api-paths.d.ts +20 -0
  70. package/lib/runtime/api-paths.js +29 -0
  71. package/lib/runtime/components/K8sAPI.d.ts +14 -1
  72. package/lib/runtime/components/K8sAPI.js +49 -10
  73. package/lib/runtime/components/K8sCrd.d.ts +1 -1
  74. package/lib/runtime/components/K8sPermissionTable.js +10 -5
  75. package/lib/runtime/components/OpenAPIPath.js +19 -2
  76. package/lib/runtime/components/_HeadingTitle.js +24 -6
  77. package/lib/runtime/components/_K8sAPIEndpoints.d.ts +8 -1
  78. package/lib/runtime/components/_K8sAPIEndpoints.js +27 -9
  79. package/lib/runtime/components/_K8sAPISchema.d.ts +9 -1
  80. package/lib/runtime/components/_K8sAPISchema.js +24 -6
  81. package/lib/runtime/components/_translation-policy.d.ts +23 -0
  82. package/lib/runtime/components/_translation-policy.js +32 -0
  83. package/lib/runtime/hooks/useTranslation.d.ts +1 -1
  84. package/lib/runtime/translation.d.ts +68 -0
  85. package/lib/runtime/translation.js +51 -0
  86. package/lib/runtime/utils.d.ts +24 -2
  87. package/lib/runtime/utils.js +87 -5
  88. package/lib/shared/constants.d.ts +9 -0
  89. package/lib/shared/constants.js +14 -0
  90. package/lib/types.d.ts +70 -0
  91. package/lib/utils/helpers.js +8 -2
  92. package/package.json +3 -1
@@ -0,0 +1,75 @@
1
+ import type { Plugin } from 'unified';
2
+ /**
3
+ * The lint pipeline, in one place, so `doom lint` and the translator cannot
4
+ * drift apart.
5
+ *
6
+ * The translator checks its own output with the rules `doom lint` runs — that
7
+ * is the point of expressing translation checks as lint rules rather than as a
8
+ * second checking system. A rule anyone adds here starts guarding
9
+ * machine-translated documents on the same day, without anyone remembering to
10
+ * register it twice.
11
+ */
12
+ type Rule = Plugin<[], never>;
13
+ /** Syntax plugins every rule needs before it can run. */
14
+ export declare const SYNTAX_PLUGINS: Rule[];
15
+ /**
16
+ * Rules that compare a translation with the source it was made from.
17
+ *
18
+ * Listed separately only so the ordering constraint below can be stated; they
19
+ * are members of {@link LINT_RULES} like every other rule.
20
+ */
21
+ export declare const TRANSLATION_PARITY_RULES: Rule[];
22
+ /**
23
+ * Rules whose verdict depends on documents other than the one being linted: the
24
+ * site's route table, the generated API modules, the configured sibling sites,
25
+ * the headings of whatever a link points at.
26
+ *
27
+ * The translator skips these. Two things have to both hold before a rule
28
+ * belongs here:
29
+ *
30
+ * 1. **It reads a tree that is mid-write.** `checkDeadLinks` builds its route
31
+ * table by scanning the docs directory. During a translation run the target
32
+ * language directory is still being filled in, so a link to a page whose
33
+ * translation has not been written yet resolves to nothing — a red that says
34
+ * only "this file was translated before that one".
35
+ * 2. **The translator could not act on it anyway.** Link targets, `href`s,
36
+ * heading anchors and api references are masked before the model sees the
37
+ * document, so they come back byte-identical to the source by construction,
38
+ * and `link-isomorphism` proves that separately. A dead link in a
39
+ * translation is a dead link in the source, and it belongs to whoever lints
40
+ * the source.
41
+ *
42
+ * `no-unmatched-anchor` is here on evidence rather than on principle. The first
43
+ * real translation run failed `zh/install/installing.mdx` over an anchor in
44
+ * `install/prepare/download.mdx` — a *different* document, whose stale
45
+ * translation had lost the heading that carries it. Nothing about the document
46
+ * being translated was wrong, the link and its anchor were both masked, and no
47
+ * repair round could have changed the outcome. A red like that costs turns and
48
+ * then blames the wrong file.
49
+ *
50
+ * They all still run in `doom lint`, over a docs tree that is complete.
51
+ */
52
+ export declare const ROUTE_DEPENDENT_RULES: Rule[];
53
+ /**
54
+ * Every rule, in the order they must run.
55
+ *
56
+ * Two orderings are load-bearing:
57
+ *
58
+ * - the two Chinese-typography rules before `chineseTypographyOnlyInChinese`,
59
+ * which drops their messages on documents that are not Chinese;
60
+ * - every pairwise rule before `checkDeadLinks`, which rewrites link urls in
61
+ * the tree as a side effect of asking rspress to resolve them. A pairwise
62
+ * rule running after it compares a rewritten translation against an
63
+ * unrewritten source and reports every link in the corpus.
64
+ */
65
+ export declare const LINT_RULES: Rule[];
66
+ /**
67
+ * What the translator checks its output with: every rule except the ones that
68
+ * need a docs tree it is in the middle of writing.
69
+ *
70
+ * Derived by subtraction rather than by listing, so a rule added to
71
+ * {@link LINT_RULES} joins the translation loop automatically — and keeps its
72
+ * position, which some of the orderings above depend on.
73
+ */
74
+ export declare const TRANSLATION_CHECK_RULES: Rule[];
75
+ export {};
@@ -0,0 +1,120 @@
1
+ import remarkDirective from 'remark-directive';
2
+ import remarkFrontmatter from 'remark-frontmatter';
3
+ import remarkGfm from 'remark-gfm';
4
+ // @ts-expect-error -- https://github.com/ilyatitovich/remark-lint-code-block-split-list/issues/2
5
+ import remarkLintCodeBlockSplitList from 'remark-lint-code-block-split-list';
6
+ import remarkLintHeadingIncrement from 'remark-lint-heading-increment';
7
+ // @ts-expect-error -- https://github.com/laysent/remark-lint-plugins/issues/51
8
+ import remarkLintLintMatchPunctuation from 'remark-lint-match-punctuation';
9
+ // @ts-expect-error -- https://github.com/laysent/remark-lint-plugins/issues/51
10
+ import remarkLintNoChinesePunctuationInNumber from 'remark-lint-no-chinese-punctuation-in-number';
11
+ import remarkLintNoDuplicateHeadingsInSection from 'remark-lint-no-duplicate-headings-in-section';
12
+ import remarkLintNoHiddenTableCell from 'remark-lint-no-hidden-table-cell';
13
+ import { checkDeadLinks, chineseTypographyOnlyInChinese, headingAnchorFormat, noDeepHeading, noDeepList, noLegacyOSNames, noMultiOpenAPIPaths, noParagraphIndent, noUnmatchedAnchor, noUnopenedFrontmatter, noUnparsedEmphasis, noUnresolvedApiRef, site, tableSize, titleRequired, translationComponentMultiset, translationEchoedSource, translationFrontmatterPreservation, translationHeadingSequence, translationJsxAttributeParity, translationLengthRatio, translationLinkIsomorphism, translationUpToDate, translationUrlResidue, unitCase, } from "./index.js";
14
+ /** Syntax plugins every rule needs before it can run. */
15
+ export const SYNTAX_PLUGINS = [
16
+ remarkDirective,
17
+ remarkFrontmatter,
18
+ remarkGfm,
19
+ ];
20
+ /**
21
+ * Rules that compare a translation with the source it was made from.
22
+ *
23
+ * Listed separately only so the ordering constraint below can be stated; they
24
+ * are members of {@link LINT_RULES} like every other rule.
25
+ */
26
+ export const TRANSLATION_PARITY_RULES = [
27
+ // Whether the pair is comparable at all comes first: nothing after it means
28
+ // anything otherwise.
29
+ translationUpToDate,
30
+ translationComponentMultiset,
31
+ translationFrontmatterPreservation,
32
+ translationHeadingSequence,
33
+ translationJsxAttributeParity,
34
+ translationLengthRatio,
35
+ translationLinkIsomorphism,
36
+ translationEchoedSource,
37
+ translationUrlResidue,
38
+ ];
39
+ /**
40
+ * Rules whose verdict depends on documents other than the one being linted: the
41
+ * site's route table, the generated API modules, the configured sibling sites,
42
+ * the headings of whatever a link points at.
43
+ *
44
+ * The translator skips these. Two things have to both hold before a rule
45
+ * belongs here:
46
+ *
47
+ * 1. **It reads a tree that is mid-write.** `checkDeadLinks` builds its route
48
+ * table by scanning the docs directory. During a translation run the target
49
+ * language directory is still being filled in, so a link to a page whose
50
+ * translation has not been written yet resolves to nothing — a red that says
51
+ * only "this file was translated before that one".
52
+ * 2. **The translator could not act on it anyway.** Link targets, `href`s,
53
+ * heading anchors and api references are masked before the model sees the
54
+ * document, so they come back byte-identical to the source by construction,
55
+ * and `link-isomorphism` proves that separately. A dead link in a
56
+ * translation is a dead link in the source, and it belongs to whoever lints
57
+ * the source.
58
+ *
59
+ * `no-unmatched-anchor` is here on evidence rather than on principle. The first
60
+ * real translation run failed `zh/install/installing.mdx` over an anchor in
61
+ * `install/prepare/download.mdx` — a *different* document, whose stale
62
+ * translation had lost the heading that carries it. Nothing about the document
63
+ * being translated was wrong, the link and its anchor were both masked, and no
64
+ * repair round could have changed the outcome. A red like that costs turns and
65
+ * then blames the wrong file.
66
+ *
67
+ * They all still run in `doom lint`, over a docs tree that is complete.
68
+ */
69
+ export const ROUTE_DEPENDENT_RULES = [
70
+ checkDeadLinks,
71
+ noUnmatchedAnchor,
72
+ noUnresolvedApiRef,
73
+ site,
74
+ ];
75
+ /**
76
+ * Every rule, in the order they must run.
77
+ *
78
+ * Two orderings are load-bearing:
79
+ *
80
+ * - the two Chinese-typography rules before `chineseTypographyOnlyInChinese`,
81
+ * which drops their messages on documents that are not Chinese;
82
+ * - every pairwise rule before `checkDeadLinks`, which rewrites link urls in
83
+ * the tree as a side effect of asking rspress to resolve them. A pairwise
84
+ * rule running after it compares a rewritten translation against an
85
+ * unrewritten source and reports every link in the corpus.
86
+ */
87
+ export const LINT_RULES = [
88
+ remarkLintCodeBlockSplitList,
89
+ remarkLintHeadingIncrement,
90
+ remarkLintLintMatchPunctuation,
91
+ remarkLintNoChinesePunctuationInNumber,
92
+ remarkLintNoDuplicateHeadingsInSection,
93
+ remarkLintNoHiddenTableCell,
94
+ chineseTypographyOnlyInChinese,
95
+ ...TRANSLATION_PARITY_RULES,
96
+ checkDeadLinks,
97
+ headingAnchorFormat,
98
+ noDeepHeading,
99
+ noDeepList,
100
+ noLegacyOSNames,
101
+ noMultiOpenAPIPaths,
102
+ noParagraphIndent,
103
+ noUnmatchedAnchor,
104
+ noUnopenedFrontmatter,
105
+ noUnparsedEmphasis,
106
+ noUnresolvedApiRef,
107
+ site,
108
+ tableSize,
109
+ titleRequired,
110
+ unitCase,
111
+ ];
112
+ /**
113
+ * What the translator checks its output with: every rule except the ones that
114
+ * need a docs tree it is in the middle of writing.
115
+ *
116
+ * Derived by subtraction rather than by listing, so a rule added to
117
+ * {@link LINT_RULES} joins the translation loop automatically — and keeps its
118
+ * position, which some of the orderings above depend on.
119
+ */
120
+ export const TRANSLATION_CHECK_RULES = LINT_RULES.filter((rule) => !ROUTE_DEPENDENT_RULES.includes(rule));
@@ -0,0 +1,17 @@
1
+ import type { Root } from 'mdast';
2
+ /**
3
+ * A translation uses exactly the components its source uses.
4
+ *
5
+ * A component is a thing on the page — a term, a callout, a link to another
6
+ * site — not a turn of phrase, so translating a page never adds or removes one.
7
+ * When the count differs, something was dropped or invented; both of the
8
+ * content-loss defects that opened this work were caught this way, and by
9
+ * nothing else:
10
+ *
11
+ * - `zh/extend/cluster_plugin.mdx`: two bullets in English, one in Chinese —
12
+ * the sentence telling readers without Customer Portal access to contact
13
+ * support was simply gone, and it happened to contain a `<Term>`.
14
+ * - `ru/install/installing.mdx`: the product name dropped out of the opening
15
+ * sentence of the installation guide.
16
+ */
17
+ export declare const translationComponentMultiset: import("unified-lint-rule").Plugin<Root, unknown>;
@@ -0,0 +1,35 @@
1
+ import { lintRule } from 'unified-lint-rule';
2
+ import { collectComponents, currentPair } from "./shared.js";
3
+ /**
4
+ * A translation uses exactly the components its source uses.
5
+ *
6
+ * A component is a thing on the page — a term, a callout, a link to another
7
+ * site — not a turn of phrase, so translating a page never adds or removes one.
8
+ * When the count differs, something was dropped or invented; both of the
9
+ * content-loss defects that opened this work were caught this way, and by
10
+ * nothing else:
11
+ *
12
+ * - `zh/extend/cluster_plugin.mdx`: two bullets in English, one in Chinese —
13
+ * the sentence telling readers without Customer Portal access to contact
14
+ * support was simply gone, and it happened to contain a `<Term>`.
15
+ * - `ru/install/installing.mdx`: the product name dropped out of the opening
16
+ * sentence of the installation guide.
17
+ */
18
+ export const translationComponentMultiset = lintRule('doom-lint:translation-component-multiset', async (tree, vfile) => {
19
+ const pair = await currentPair(tree, vfile);
20
+ if (!pair) {
21
+ return;
22
+ }
23
+ const expected = collectComponents(pair.sourceTree);
24
+ const actual = collectComponents(tree);
25
+ for (const name of new Set([...expected.keys(), ...actual.keys()])) {
26
+ const want = expected.get(name) ?? 0;
27
+ const got = actual.get(name) ?? 0;
28
+ if (want === got) {
29
+ continue;
30
+ }
31
+ vfile.message(got < want
32
+ ? `Translation dropped ${want - got} \`<${name}>\` (source has ${want}, this has ${got}) — content that was in the source is missing here.`
33
+ : `Translation invented ${got - want} \`<${name}>\` (source has ${want}, this has ${got}).`, tree);
34
+ }
35
+ });
@@ -0,0 +1,2 @@
1
+ import type { Root } from 'mdast';
2
+ export declare const translationEchoedSource: import("unified-lint-rule").Plugin<Root, unknown>;
@@ -0,0 +1,37 @@
1
+ import { lintRule } from 'unified-lint-rule';
2
+ import { collectProseText, currentPair } from "./shared.js";
3
+ /**
4
+ * A translation must not be the source.
5
+ *
6
+ * The failure is the model handing back what it was given: frontmatter title
7
+ * and description come out translated — those are produced separately — while
8
+ * the body is returned verbatim. Every structural check is satisfied by this,
9
+ * because structurally it *is* the source: same links, same components, same
10
+ * headings, same length.
11
+ *
12
+ * The test is prose identity rather than "how much of it looks Chinese".
13
+ * Sampling the script does not work: reference pages in this corpus run as low
14
+ * as 2% native characters and are perfectly good translations — they are mostly
15
+ * field names — so any threshold that catches an echo also condemns them.
16
+ * Identity has no threshold to get wrong, and on 1050 real pairs it selected
17
+ * exactly three documents, all three of them genuinely untranslated.
18
+ *
19
+ * What it deliberately does not catch is a *partly* echoed document. That needs
20
+ * a reader, not a comparison.
21
+ */
22
+ const normalise = (text) => text.replace(/\s+/g, ' ').trim();
23
+ /** Below this, identity means the page is a heading and a component. */
24
+ const MIN_PROSE_CHARS = 200;
25
+ export const translationEchoedSource = lintRule('doom-lint:translation-echoed-source', async (tree, vfile) => {
26
+ const pair = await currentPair(tree, vfile);
27
+ if (!pair || pair.isCopyOnly) {
28
+ return;
29
+ }
30
+ const source = normalise(collectProseText(pair.sourceTree));
31
+ if (source.length < MIN_PROSE_CHARS) {
32
+ return;
33
+ }
34
+ if (normalise(collectProseText(tree)) === source) {
35
+ vfile.message(`Translation is the source: every word of prose came back unchanged in ${pair.sourceLang}. The model echoed the document instead of translating it.`, tree);
36
+ }
37
+ });
@@ -0,0 +1,2 @@
1
+ import type { Root } from 'mdast';
2
+ export declare const translationFrontmatterPreservation: import("unified-lint-rule").Plugin<Root, unknown>;
@@ -0,0 +1,36 @@
1
+ import { lintRule } from 'unified-lint-rule';
2
+ import { currentPair } from "./shared.js";
3
+ /**
4
+ * Frontmatter is configuration, not copy.
5
+ *
6
+ * `weight` orders the sidebar, `sourceSHA` pairs the document with its source,
7
+ * `i18n` and the rest steer the build. Only `title` and `description` are read
8
+ * by a human, and only those two are translated. Anything else that differs
9
+ * between a source and its translation changes how the site is built for one
10
+ * language and not the other.
11
+ */
12
+ const TRANSLATED_KEYS = new Set(['title', 'description']);
13
+ // `sourceSHA` is written by the translator and `i18n` is deliberately dropped
14
+ // from the translation — neither is a divergence.
15
+ const TRANSLATOR_OWNED_KEYS = new Set(['sourceSHA', 'i18n']);
16
+ export const translationFrontmatterPreservation = lintRule('doom-lint:translation-frontmatter-preservation', async (tree, vfile) => {
17
+ const pair = await currentPair(tree, vfile);
18
+ if (!pair) {
19
+ return;
20
+ }
21
+ const keys = new Set([
22
+ ...Object.keys(pair.sourceFrontmatter),
23
+ ...Object.keys(pair.targetFrontmatter),
24
+ ]);
25
+ for (const key of keys) {
26
+ if (TRANSLATED_KEYS.has(key) || TRANSLATOR_OWNED_KEYS.has(key)) {
27
+ continue;
28
+ }
29
+ const expected = JSON.stringify(pair.sourceFrontmatter[key] ?? null);
30
+ const actual = JSON.stringify(pair.targetFrontmatter[key] ?? null);
31
+ if (expected === actual) {
32
+ continue;
33
+ }
34
+ vfile.message(`Translation changed frontmatter \`${key}\`: source has ${expected}, this has ${actual}. Only \`title\` and \`description\` are translated.`, tree);
35
+ }
36
+ });
@@ -0,0 +1,12 @@
1
+ import type { Root } from 'mdast';
2
+ /**
3
+ * A translation keeps its source's heading structure.
4
+ *
5
+ * Headings are the page's skeleton and its anchors: a lost or promoted heading
6
+ * silently changes the table of contents and breaks every link that pointed at
7
+ * it. Translating the text of a heading never changes its level.
8
+ *
9
+ * Honest caveat: this has never fired on real damage in this corpus (0 of 1764
10
+ * pairs). It is a regression guard, not a demonstrated detector.
11
+ */
12
+ export declare const translationHeadingSequence: import("unified-lint-rule").Plugin<Root, unknown>;
@@ -0,0 +1,25 @@
1
+ import { lintRule } from 'unified-lint-rule';
2
+ import { collectHeadingDepths, currentPair } from "./shared.js";
3
+ /**
4
+ * A translation keeps its source's heading structure.
5
+ *
6
+ * Headings are the page's skeleton and its anchors: a lost or promoted heading
7
+ * silently changes the table of contents and breaks every link that pointed at
8
+ * it. Translating the text of a heading never changes its level.
9
+ *
10
+ * Honest caveat: this has never fired on real damage in this corpus (0 of 1764
11
+ * pairs). It is a regression guard, not a demonstrated detector.
12
+ */
13
+ export const translationHeadingSequence = lintRule('doom-lint:translation-heading-sequence', async (tree, vfile) => {
14
+ const pair = await currentPair(tree, vfile);
15
+ if (!pair) {
16
+ return;
17
+ }
18
+ const expected = collectHeadingDepths(pair.sourceTree);
19
+ const actual = collectHeadingDepths(tree);
20
+ if (expected.length === actual.length &&
21
+ expected.every((depth, index) => depth === actual[index])) {
22
+ return;
23
+ }
24
+ vfile.message(`Translation changed the heading structure: source is ${expected.join('-') || '(none)'}, this is ${actual.join('-') || '(none)'}.`, tree);
25
+ });
@@ -0,0 +1,24 @@
1
+ /**
2
+ * Checks that compare a translation with the source it was made from.
3
+ *
4
+ * Ordinary lint rules read one document; these read two. That is the only thing
5
+ * that separates them, and it is why they live together: the pairing logic and
6
+ * the "say nothing when the pair is not trustworthy" discipline are shared, in
7
+ * `shared.ts`.
8
+ *
9
+ * They are ordinary lint rules in every other respect — same engine, same
10
+ * `<!-- lint disable -->` control, same editor integration — so a translation
11
+ * problem someone notices becomes a rule here, and hand-written documents get
12
+ * the benefit of it too. There is deliberately not a second checking system for
13
+ * translations.
14
+ */
15
+ export * from './component-multiset.ts';
16
+ export * from './echoed-source.ts';
17
+ export * from './frontmatter-preservation.ts';
18
+ export * from './heading-sequence.ts';
19
+ export * from './jsx-attribute-parity.ts';
20
+ export * from './length-ratio.ts';
21
+ export * from './link-isomorphism.ts';
22
+ export * from './terminology-adherence.ts';
23
+ export * from './up-to-date.ts';
24
+ export * from './url-residue.ts';
@@ -0,0 +1,24 @@
1
+ /**
2
+ * Checks that compare a translation with the source it was made from.
3
+ *
4
+ * Ordinary lint rules read one document; these read two. That is the only thing
5
+ * that separates them, and it is why they live together: the pairing logic and
6
+ * the "say nothing when the pair is not trustworthy" discipline are shared, in
7
+ * `shared.ts`.
8
+ *
9
+ * They are ordinary lint rules in every other respect — same engine, same
10
+ * `<!-- lint disable -->` control, same editor integration — so a translation
11
+ * problem someone notices becomes a rule here, and hand-written documents get
12
+ * the benefit of it too. There is deliberately not a second checking system for
13
+ * translations.
14
+ */
15
+ export * from "./component-multiset.js";
16
+ export * from "./echoed-source.js";
17
+ export * from "./frontmatter-preservation.js";
18
+ export * from "./heading-sequence.js";
19
+ export * from "./jsx-attribute-parity.js";
20
+ export * from "./length-ratio.js";
21
+ export * from "./link-isomorphism.js";
22
+ export * from "./terminology-adherence.js";
23
+ export * from "./up-to-date.js";
24
+ export * from "./url-residue.js";
@@ -0,0 +1,14 @@
1
+ import type { Root } from 'mdast';
2
+ /**
3
+ * Component attributes are identifiers, and identifiers survive translation
4
+ * unchanged.
5
+ *
6
+ * `<Term name="productShort" />`, `<K8sAPI name="backups.velero.io" />`,
7
+ * `<OpenAPIPath path="/v1/alerthistories" />` — none of these is prose, and a
8
+ * translation that changes one produces a page that renders wrong while the
9
+ * build stays green. The exceptions are declared in one place,
10
+ * `runtime/components/_translation-policy.ts`, and are the same list the
11
+ * translator's masking uses: what may be translated is exactly what is not
12
+ * protected.
13
+ */
14
+ export declare const translationJsxAttributeParity: import("unified-lint-rule").Plugin<Root, unknown>;
@@ -0,0 +1,47 @@
1
+ import { lintRule } from 'unified-lint-rule';
2
+ import { TRANSLATABLE_JSX_ATTRS } from "../../runtime/components/_translation-policy.js";
3
+ import { collectJsxAttributes, currentPair, diffMultiset } from "./shared.js";
4
+ /**
5
+ * `src` and `href` are compared by `translation-link-isomorphism` instead,
6
+ * which resolves them first. They legitimately differ as *written*: assets are
7
+ * not copied per language, so a translation points back into the source tree —
8
+ * `../../../en/networking/x.png` where the source says `./x.png`. Both name the
9
+ * same file. Comparing the strings reports every illustrated page in the
10
+ * corpus, which is what it did before this exemption existed.
11
+ */
12
+ const RESOLVED_ELSEWHERE = new Set(['href', 'src']);
13
+ const isExempt = (key) => {
14
+ const [element, attribute] = key.split('.');
15
+ return (RESOLVED_ELSEWHERE.has(attribute) ||
16
+ !!TRANSLATABLE_JSX_ATTRS[element]?.includes(attribute));
17
+ };
18
+ /**
19
+ * Component attributes are identifiers, and identifiers survive translation
20
+ * unchanged.
21
+ *
22
+ * `<Term name="productShort" />`, `<K8sAPI name="backups.velero.io" />`,
23
+ * `<OpenAPIPath path="/v1/alerthistories" />` — none of these is prose, and a
24
+ * translation that changes one produces a page that renders wrong while the
25
+ * build stays green. The exceptions are declared in one place,
26
+ * `runtime/components/_translation-policy.ts`, and are the same list the
27
+ * translator's masking uses: what may be translated is exactly what is not
28
+ * protected.
29
+ */
30
+ export const translationJsxAttributeParity = lintRule('doom-lint:translation-jsx-attribute-parity', async (tree, vfile) => {
31
+ const pair = await currentPair(tree, vfile);
32
+ if (!pair) {
33
+ return;
34
+ }
35
+ const expected = collectJsxAttributes(pair.sourceTree);
36
+ const actual = collectJsxAttributes(tree);
37
+ for (const key of new Set([...expected.keys(), ...actual.keys()])) {
38
+ if (isExempt(key)) {
39
+ continue;
40
+ }
41
+ const { missing, extra } = diffMultiset(expected.get(key) ?? [], actual.get(key) ?? []);
42
+ if (!missing.length && !extra.length) {
43
+ continue;
44
+ }
45
+ vfile.message(`Translation changed \`${key}\`, which is an identifier rather than prose: source has ${missing.length ? missing.map((v) => `\`${v}\``).join(', ') : '(nothing extra)'}, this has ${extra.length ? extra.map((v) => `\`${v}\``).join(', ') : '(nothing extra)'}.`, tree);
46
+ }
47
+ });
@@ -0,0 +1,2 @@
1
+ import type { Root } from 'mdast';
2
+ export declare const translationLengthRatio: import("unified-lint-rule").Plugin<Root, unknown>;
@@ -0,0 +1,49 @@
1
+ import { lintRule } from 'unified-lint-rule';
2
+ import { collectProseText, currentPair } from "./shared.js";
3
+ /**
4
+ * A translation is roughly as long as its source, in the way that language is.
5
+ *
6
+ * This is the one check that catches a translation which simply stops — the
7
+ * model ran out of room, or answered with a summary. It cannot be tight,
8
+ * because languages differ in density, and it has to be calibrated against the
9
+ * measure the rule actually uses. Measured over 1050 real pairs, on **prose
10
+ * only** (code, inline code and component attributes excluded):
11
+ *
12
+ * zh min 0.247 p05 0.288 p50 0.394 p95 0.541 max 1.000
13
+ * ru min 0.644 p05 0.987 p50 1.090 p95 1.209 max 1.714
14
+ *
15
+ * Chinese says the same thing in roughly two fifths of the characters, so a
16
+ * band borrowed from a whole-file byte ratio sits *inside* the healthy
17
+ * distribution and condemns ordinary pages — which is what happened before
18
+ * these numbers were measured. The bands below sit well outside the observed
19
+ * range: a page has to be out of family, not merely at the edge of it.
20
+ *
21
+ * Re-measure before changing them, and measure the same thing the rule measures.
22
+ */
23
+ const RATIO_BANDS = {
24
+ zh: { floor: 0.12, ceiling: 1.5 },
25
+ ru: { floor: 0.35, ceiling: 2.5 },
26
+ };
27
+ /** Below this many characters the ratio is noise, not signal. */
28
+ const MIN_PROSE_CHARS = 200;
29
+ export const translationLengthRatio = lintRule('doom-lint:translation-length-ratio', async (tree, vfile) => {
30
+ const pair = await currentPair(tree, vfile);
31
+ if (!pair || pair.isCopyOnly) {
32
+ return;
33
+ }
34
+ const band = RATIO_BANDS[pair.targetLang];
35
+ if (!band) {
36
+ return;
37
+ }
38
+ const source = collectProseText(pair.sourceTree).length;
39
+ if (source < MIN_PROSE_CHARS) {
40
+ return;
41
+ }
42
+ const ratio = collectProseText(tree).length / source;
43
+ if (ratio < band.floor) {
44
+ vfile.message(`Translation is far shorter than its source (${ratio.toFixed(2)}× the prose, expected at least ${band.floor}× for ${pair.targetLang}) — it looks truncated or summarised.`, tree);
45
+ }
46
+ else if (ratio > band.ceiling) {
47
+ vfile.message(`Translation is far longer than its source (${ratio.toFixed(2)}× the prose, expected at most ${band.ceiling}× for ${pair.targetLang}) — it looks like content was added or repeated.`, tree);
48
+ }
49
+ });
@@ -0,0 +1,26 @@
1
+ import type { Root } from 'mdast';
2
+ /**
3
+ * A translation points at exactly the same places its source points at.
4
+ *
5
+ * Not "its links resolve" — that is a much weaker property, and it is the one
6
+ * the build happens to check. A link can be rewritten into a different, still
7
+ * existing page and the build stays green while the reader is sent somewhere
8
+ * else. Every link is therefore resolved against the position of the document
9
+ * holding it and stripped of its language segment, and the resulting multisets
10
+ * must match.
11
+ *
12
+ * Resolving is what makes the comparison possible: a translation's asset links
13
+ * legitimately read `../../../en/networking/x.png` where the source reads
14
+ * `./x.png`, because assets are not copied per language. Both name the same
15
+ * file, so they compare equal — while every corruption measured on this corpus
16
+ * does not:
17
+ *
18
+ * - a `<ExternalSiteLink … href="/global/install.html" />` flattened into
19
+ * `[…](../global/install.html)`;
20
+ * - `../virtualization/virtualization/virtual_machine/…` collapsed into
21
+ * `../virtualization/virtualization_virtual_machine/…`;
22
+ * - `../global_dr.mdx` rewritten as `../global.dr.mdx`;
23
+ * - `how_to/` rewritten as `how-to/`;
24
+ * - the same link generated twice.
25
+ */
26
+ export declare const translationLinkIsomorphism: import("unified-lint-rule").Plugin<Root, unknown>;
@@ -0,0 +1,45 @@
1
+ import { lintRule } from 'unified-lint-rule';
2
+ import { collectLinkTargets, currentPair, diffMultiset, docDirInRoot, } from "./shared.js";
3
+ const preview = (values) => values
4
+ .slice(0, 5)
5
+ .map((value) => `\`${value}\``)
6
+ .join(', ') + (values.length > 5 ? `, … (${values.length} total)` : '');
7
+ /**
8
+ * A translation points at exactly the same places its source points at.
9
+ *
10
+ * Not "its links resolve" — that is a much weaker property, and it is the one
11
+ * the build happens to check. A link can be rewritten into a different, still
12
+ * existing page and the build stays green while the reader is sent somewhere
13
+ * else. Every link is therefore resolved against the position of the document
14
+ * holding it and stripped of its language segment, and the resulting multisets
15
+ * must match.
16
+ *
17
+ * Resolving is what makes the comparison possible: a translation's asset links
18
+ * legitimately read `../../../en/networking/x.png` where the source reads
19
+ * `./x.png`, because assets are not copied per language. Both name the same
20
+ * file, so they compare equal — while every corruption measured on this corpus
21
+ * does not:
22
+ *
23
+ * - a `<ExternalSiteLink … href="/global/install.html" />` flattened into
24
+ * `[…](../global/install.html)`;
25
+ * - `../virtualization/virtualization/virtual_machine/…` collapsed into
26
+ * `../virtualization/virtualization_virtual_machine/…`;
27
+ * - `../global_dr.mdx` rewritten as `../global.dr.mdx`;
28
+ * - `how_to/` rewritten as `how-to/`;
29
+ * - the same link generated twice.
30
+ */
31
+ export const translationLinkIsomorphism = lintRule('doom-lint:translation-link-isomorphism', async (tree, vfile) => {
32
+ const pair = await currentPair(tree, vfile);
33
+ if (!pair) {
34
+ return;
35
+ }
36
+ const expected = collectLinkTargets(pair.sourceTree, docDirInRoot(pair.sourceLang, pair.relativePath));
37
+ const actual = collectLinkTargets(tree, docDirInRoot(pair.targetLang, pair.relativePath));
38
+ const { missing, extra } = diffMultiset(expected, actual);
39
+ if (missing.length) {
40
+ vfile.message(`Translation lost ${missing.length} link target(s) the source has: ${preview(missing)}.`, tree);
41
+ }
42
+ if (extra.length) {
43
+ vfile.message(`Translation points at ${extra.length} target(s) the source does not: ${preview(extra)}.`, tree);
44
+ }
45
+ });