@alauda/doom 2.5.4 → 2.6.1

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 (94) 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 +19 -2
  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 +73 -0
  42. package/lib/remark-lint/rule-sets.js +114 -0
  43. package/lib/remark-lint/syntax-plugins.d.ts +32 -0
  44. package/lib/remark-lint/syntax-plugins.js +46 -0
  45. package/lib/remark-lint/translation-parity/component-multiset.d.ts +17 -0
  46. package/lib/remark-lint/translation-parity/component-multiset.js +35 -0
  47. package/lib/remark-lint/translation-parity/echoed-source.d.ts +2 -0
  48. package/lib/remark-lint/translation-parity/echoed-source.js +37 -0
  49. package/lib/remark-lint/translation-parity/frontmatter-preservation.d.ts +2 -0
  50. package/lib/remark-lint/translation-parity/frontmatter-preservation.js +36 -0
  51. package/lib/remark-lint/translation-parity/heading-sequence.d.ts +12 -0
  52. package/lib/remark-lint/translation-parity/heading-sequence.js +25 -0
  53. package/lib/remark-lint/translation-parity/index.d.ts +24 -0
  54. package/lib/remark-lint/translation-parity/index.js +24 -0
  55. package/lib/remark-lint/translation-parity/jsx-attribute-parity.d.ts +14 -0
  56. package/lib/remark-lint/translation-parity/jsx-attribute-parity.js +47 -0
  57. package/lib/remark-lint/translation-parity/length-ratio.d.ts +2 -0
  58. package/lib/remark-lint/translation-parity/length-ratio.js +49 -0
  59. package/lib/remark-lint/translation-parity/link-isomorphism.d.ts +34 -0
  60. package/lib/remark-lint/translation-parity/link-isomorphism.js +81 -0
  61. package/lib/remark-lint/translation-parity/shared.d.ts +110 -0
  62. package/lib/remark-lint/translation-parity/shared.js +286 -0
  63. package/lib/remark-lint/translation-parity/terminology-adherence.d.ts +2 -0
  64. package/lib/remark-lint/translation-parity/terminology-adherence.js +67 -0
  65. package/lib/remark-lint/translation-parity/up-to-date.d.ts +11 -0
  66. package/lib/remark-lint/translation-parity/up-to-date.js +21 -0
  67. package/lib/remark-lint/translation-parity/url-residue.d.ts +3 -0
  68. package/lib/remark-lint/translation-parity/url-residue.js +67 -0
  69. package/lib/remarkrc.d.ts +1 -1
  70. package/lib/remarkrc.js +7 -34
  71. package/lib/runtime/api-paths.d.ts +20 -0
  72. package/lib/runtime/api-paths.js +29 -0
  73. package/lib/runtime/components/K8sAPI.d.ts +14 -1
  74. package/lib/runtime/components/K8sAPI.js +49 -10
  75. package/lib/runtime/components/K8sCrd.d.ts +1 -1
  76. package/lib/runtime/components/K8sPermissionTable.js +10 -5
  77. package/lib/runtime/components/OpenAPIPath.js +19 -2
  78. package/lib/runtime/components/_HeadingTitle.js +24 -6
  79. package/lib/runtime/components/_K8sAPIEndpoints.d.ts +8 -1
  80. package/lib/runtime/components/_K8sAPIEndpoints.js +27 -9
  81. package/lib/runtime/components/_K8sAPISchema.d.ts +9 -1
  82. package/lib/runtime/components/_K8sAPISchema.js +24 -6
  83. package/lib/runtime/components/_translation-policy.d.ts +23 -0
  84. package/lib/runtime/components/_translation-policy.js +32 -0
  85. package/lib/runtime/hooks/useTranslation.d.ts +1 -1
  86. package/lib/runtime/translation.d.ts +68 -0
  87. package/lib/runtime/translation.js +51 -0
  88. package/lib/runtime/utils.d.ts +24 -2
  89. package/lib/runtime/utils.js +87 -5
  90. package/lib/shared/constants.d.ts +9 -0
  91. package/lib/shared/constants.js +14 -0
  92. package/lib/types.d.ts +70 -0
  93. package/lib/utils/helpers.js +8 -2
  94. package/package.json +3 -1
@@ -0,0 +1,73 @@
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
+ export { SYNTAX_PLUGINS } from './syntax-plugins.ts';
14
+ /**
15
+ * Rules that compare a translation with the source it was made from.
16
+ *
17
+ * Listed separately only so the ordering constraint below can be stated; they
18
+ * are members of {@link LINT_RULES} like every other rule.
19
+ */
20
+ export declare const TRANSLATION_PARITY_RULES: Rule[];
21
+ /**
22
+ * Rules whose verdict depends on documents other than the one being linted: the
23
+ * site's route table, the generated API modules, the configured sibling sites,
24
+ * the headings of whatever a link points at.
25
+ *
26
+ * The translator skips these. Two things have to both hold before a rule
27
+ * belongs here:
28
+ *
29
+ * 1. **It reads a tree that is mid-write.** `checkDeadLinks` builds its route
30
+ * table by scanning the docs directory. During a translation run the target
31
+ * language directory is still being filled in, so a link to a page whose
32
+ * translation has not been written yet resolves to nothing — a red that says
33
+ * only "this file was translated before that one".
34
+ * 2. **The translator could not act on it anyway.** Link targets, `href`s,
35
+ * heading anchors and api references are masked before the model sees the
36
+ * document, so they come back byte-identical to the source by construction,
37
+ * and `link-isomorphism` proves that separately. A dead link in a
38
+ * translation is a dead link in the source, and it belongs to whoever lints
39
+ * the source.
40
+ *
41
+ * `no-unmatched-anchor` is here on evidence rather than on principle. The first
42
+ * real translation run failed `zh/install/installing.mdx` over an anchor in
43
+ * `install/prepare/download.mdx` — a *different* document, whose stale
44
+ * translation had lost the heading that carries it. Nothing about the document
45
+ * being translated was wrong, the link and its anchor were both masked, and no
46
+ * repair round could have changed the outcome. A red like that costs turns and
47
+ * then blames the wrong file.
48
+ *
49
+ * They all still run in `doom lint`, over a docs tree that is complete.
50
+ */
51
+ export declare const ROUTE_DEPENDENT_RULES: Rule[];
52
+ /**
53
+ * Every rule, in the order they must run.
54
+ *
55
+ * Two orderings are load-bearing:
56
+ *
57
+ * - the two Chinese-typography rules before `chineseTypographyOnlyInChinese`,
58
+ * which drops their messages on documents that are not Chinese;
59
+ * - every pairwise rule before `checkDeadLinks`, which rewrites link urls in
60
+ * the tree as a side effect of asking rspress to resolve them. A pairwise
61
+ * rule running after it compares a rewritten translation against an
62
+ * unrewritten source and reports every link in the corpus.
63
+ */
64
+ export declare const LINT_RULES: Rule[];
65
+ /**
66
+ * What the translator checks its output with: every rule except the ones that
67
+ * need a docs tree it is in the middle of writing.
68
+ *
69
+ * Derived by subtraction rather than by listing, so a rule added to
70
+ * {@link LINT_RULES} joins the translation loop automatically — and keeps its
71
+ * position, which some of the orderings above depend on.
72
+ */
73
+ export declare const TRANSLATION_CHECK_RULES: Rule[];
@@ -0,0 +1,114 @@
1
+ // @ts-expect-error -- https://github.com/ilyatitovich/remark-lint-code-block-split-list/issues/2
2
+ import remarkLintCodeBlockSplitList from 'remark-lint-code-block-split-list';
3
+ import remarkLintHeadingIncrement from 'remark-lint-heading-increment';
4
+ // @ts-expect-error -- https://github.com/laysent/remark-lint-plugins/issues/51
5
+ import remarkLintLintMatchPunctuation from 'remark-lint-match-punctuation';
6
+ // @ts-expect-error -- https://github.com/laysent/remark-lint-plugins/issues/51
7
+ import remarkLintNoChinesePunctuationInNumber from 'remark-lint-no-chinese-punctuation-in-number';
8
+ import remarkLintNoDuplicateHeadingsInSection from 'remark-lint-no-duplicate-headings-in-section';
9
+ import remarkLintNoHiddenTableCell from 'remark-lint-no-hidden-table-cell';
10
+ 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";
11
+ // The syntax stack lives in its own module so `translation-parity` can parse
12
+ // the source side with it without importing the rules that import it back.
13
+ export { SYNTAX_PLUGINS } from "./syntax-plugins.js";
14
+ /**
15
+ * Rules that compare a translation with the source it was made from.
16
+ *
17
+ * Listed separately only so the ordering constraint below can be stated; they
18
+ * are members of {@link LINT_RULES} like every other rule.
19
+ */
20
+ export const TRANSLATION_PARITY_RULES = [
21
+ // Whether the pair is comparable at all comes first: nothing after it means
22
+ // anything otherwise.
23
+ translationUpToDate,
24
+ translationComponentMultiset,
25
+ translationFrontmatterPreservation,
26
+ translationHeadingSequence,
27
+ translationJsxAttributeParity,
28
+ translationLengthRatio,
29
+ translationLinkIsomorphism,
30
+ translationEchoedSource,
31
+ translationUrlResidue,
32
+ ];
33
+ /**
34
+ * Rules whose verdict depends on documents other than the one being linted: the
35
+ * site's route table, the generated API modules, the configured sibling sites,
36
+ * the headings of whatever a link points at.
37
+ *
38
+ * The translator skips these. Two things have to both hold before a rule
39
+ * belongs here:
40
+ *
41
+ * 1. **It reads a tree that is mid-write.** `checkDeadLinks` builds its route
42
+ * table by scanning the docs directory. During a translation run the target
43
+ * language directory is still being filled in, so a link to a page whose
44
+ * translation has not been written yet resolves to nothing — a red that says
45
+ * only "this file was translated before that one".
46
+ * 2. **The translator could not act on it anyway.** Link targets, `href`s,
47
+ * heading anchors and api references are masked before the model sees the
48
+ * document, so they come back byte-identical to the source by construction,
49
+ * and `link-isomorphism` proves that separately. A dead link in a
50
+ * translation is a dead link in the source, and it belongs to whoever lints
51
+ * the source.
52
+ *
53
+ * `no-unmatched-anchor` is here on evidence rather than on principle. The first
54
+ * real translation run failed `zh/install/installing.mdx` over an anchor in
55
+ * `install/prepare/download.mdx` — a *different* document, whose stale
56
+ * translation had lost the heading that carries it. Nothing about the document
57
+ * being translated was wrong, the link and its anchor were both masked, and no
58
+ * repair round could have changed the outcome. A red like that costs turns and
59
+ * then blames the wrong file.
60
+ *
61
+ * They all still run in `doom lint`, over a docs tree that is complete.
62
+ */
63
+ export const ROUTE_DEPENDENT_RULES = [
64
+ checkDeadLinks,
65
+ noUnmatchedAnchor,
66
+ noUnresolvedApiRef,
67
+ site,
68
+ ];
69
+ /**
70
+ * Every rule, in the order they must run.
71
+ *
72
+ * Two orderings are load-bearing:
73
+ *
74
+ * - the two Chinese-typography rules before `chineseTypographyOnlyInChinese`,
75
+ * which drops their messages on documents that are not Chinese;
76
+ * - every pairwise rule before `checkDeadLinks`, which rewrites link urls in
77
+ * the tree as a side effect of asking rspress to resolve them. A pairwise
78
+ * rule running after it compares a rewritten translation against an
79
+ * unrewritten source and reports every link in the corpus.
80
+ */
81
+ export const LINT_RULES = [
82
+ remarkLintCodeBlockSplitList,
83
+ remarkLintHeadingIncrement,
84
+ remarkLintLintMatchPunctuation,
85
+ remarkLintNoChinesePunctuationInNumber,
86
+ remarkLintNoDuplicateHeadingsInSection,
87
+ remarkLintNoHiddenTableCell,
88
+ chineseTypographyOnlyInChinese,
89
+ ...TRANSLATION_PARITY_RULES,
90
+ checkDeadLinks,
91
+ headingAnchorFormat,
92
+ noDeepHeading,
93
+ noDeepList,
94
+ noLegacyOSNames,
95
+ noMultiOpenAPIPaths,
96
+ noParagraphIndent,
97
+ noUnmatchedAnchor,
98
+ noUnopenedFrontmatter,
99
+ noUnparsedEmphasis,
100
+ noUnresolvedApiRef,
101
+ site,
102
+ tableSize,
103
+ titleRequired,
104
+ unitCase,
105
+ ];
106
+ /**
107
+ * What the translator checks its output with: every rule except the ones that
108
+ * need a docs tree it is in the middle of writing.
109
+ *
110
+ * Derived by subtraction rather than by listing, so a rule added to
111
+ * {@link LINT_RULES} joins the translation loop automatically — and keeps its
112
+ * position, which some of the orderings above depend on.
113
+ */
114
+ export const TRANSLATION_CHECK_RULES = LINT_RULES.filter((rule) => !ROUTE_DEPENDENT_RULES.includes(rule));
@@ -0,0 +1,32 @@
1
+ import type { Root } from 'mdast';
2
+ import type { Plugin } from 'unified';
3
+ /**
4
+ * The syntax extensions a document is parsed with, in one place.
5
+ *
6
+ * This exists because the `translation-parity` rules compare two trees, and for
7
+ * a comparison to mean anything both trees have to have been parsed the same
8
+ * way. They were not: the document being linted came through the lint pipeline
9
+ * (these plugins), while the source it was compared against was parsed with the
10
+ * site's `mdxProcessor`, which has no `remark-directive`. Anything directive
11
+ * syntax touches — a port in `http://host:8080`, a tag in `image:1.25`, a time
12
+ * in `10:30` — then became a `textDirective` on one side and stayed plain text
13
+ * on the other, and the rules reported the difference as damage the translator
14
+ * could not repair, because nothing it could write would make the two sides
15
+ * agree.
16
+ *
17
+ * `remark-directive` is in the list because the site renders with it
18
+ * (`plugins/directives`), so it is what the published page actually is.
19
+ */
20
+ export declare const SYNTAX_PLUGINS: Plugin<[], never>[];
21
+ /** Parse-only view of the stack — the rules never stringify the source. */
22
+ export interface SyntaxProcessor {
23
+ parse: (content: string) => Root;
24
+ }
25
+ /**
26
+ * Parses a document exactly as the lint pipeline does — the reference side of
27
+ * every `translation-parity` comparison.
28
+ */
29
+ export declare const syntaxProcessor: {
30
+ md: SyntaxProcessor;
31
+ mdx: SyntaxProcessor;
32
+ };
@@ -0,0 +1,46 @@
1
+ import remarkDirective from 'remark-directive';
2
+ import remarkFrontmatter from 'remark-frontmatter';
3
+ import remarkGfm from 'remark-gfm';
4
+ import remarkMdx from 'remark-mdx';
5
+ import remarkParse from 'remark-parse';
6
+ import { unified } from 'unified';
7
+ /**
8
+ * The syntax extensions a document is parsed with, in one place.
9
+ *
10
+ * This exists because the `translation-parity` rules compare two trees, and for
11
+ * a comparison to mean anything both trees have to have been parsed the same
12
+ * way. They were not: the document being linted came through the lint pipeline
13
+ * (these plugins), while the source it was compared against was parsed with the
14
+ * site's `mdxProcessor`, which has no `remark-directive`. Anything directive
15
+ * syntax touches — a port in `http://host:8080`, a tag in `image:1.25`, a time
16
+ * in `10:30` — then became a `textDirective` on one side and stayed plain text
17
+ * on the other, and the rules reported the difference as damage the translator
18
+ * could not repair, because nothing it could write would make the two sides
19
+ * agree.
20
+ *
21
+ * `remark-directive` is in the list because the site renders with it
22
+ * (`plugins/directives`), so it is what the published page actually is.
23
+ */
24
+ export const SYNTAX_PLUGINS = [
25
+ remarkDirective,
26
+ remarkFrontmatter,
27
+ remarkGfm,
28
+ ];
29
+ const build = (mdx) => {
30
+ let processor = unified().use(remarkParse);
31
+ for (const plugin of SYNTAX_PLUGINS) {
32
+ processor = processor.use(plugin);
33
+ }
34
+ if (mdx) {
35
+ processor = processor.use(remarkMdx);
36
+ }
37
+ return processor.freeze();
38
+ };
39
+ /**
40
+ * Parses a document exactly as the lint pipeline does — the reference side of
41
+ * every `translation-parity` comparison.
42
+ */
43
+ export const syntaxProcessor = {
44
+ md: build(false),
45
+ mdx: build(true),
46
+ };
@@ -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,34 @@
1
+ import type { Root } from 'mdast';
2
+ export declare const partitionAbsorbed: (missing: readonly string[], extra: readonly string[]) => {
3
+ absorbed: {
4
+ target: string;
5
+ suffix: string;
6
+ }[];
7
+ lost: string[];
8
+ unmatched: string[];
9
+ };
10
+ /**
11
+ * A translation points at exactly the same places its source points at.
12
+ *
13
+ * Not "its links resolve" — that is a much weaker property, and it is the one
14
+ * the build happens to check. A link can be rewritten into a different, still
15
+ * existing page and the build stays green while the reader is sent somewhere
16
+ * else. Every link is therefore resolved against the position of the document
17
+ * holding it and stripped of its language segment, and the resulting multisets
18
+ * must match.
19
+ *
20
+ * Resolving is what makes the comparison possible: a translation's asset links
21
+ * legitimately read `../../../en/networking/x.png` where the source reads
22
+ * `./x.png`, because assets are not copied per language. Both name the same
23
+ * file, so they compare equal — while every corruption measured on this corpus
24
+ * does not:
25
+ *
26
+ * - a `<ExternalSiteLink … href="/global/install.html" />` flattened into
27
+ * `[…](../global/install.html)`;
28
+ * - `../virtualization/virtualization/virtual_machine/…` collapsed into
29
+ * `../virtualization/virtualization_virtual_machine/…`;
30
+ * - `../global_dr.mdx` rewritten as `../global.dr.mdx`;
31
+ * - `how_to/` rewritten as `how-to/`;
32
+ * - the same link generated twice.
33
+ */
34
+ export declare const translationLinkIsomorphism: import("unified-lint-rule").Plugin<Root, unknown>;