@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.
- package/lib/cli/api.d.ts +2 -0
- package/lib/cli/api.js +147 -0
- package/lib/cli/helpers.d.ts +1 -7
- package/lib/cli/helpers.js +4 -41
- package/lib/cli/index.js +2 -0
- package/lib/cli/translate-agent.d.ts +81 -0
- package/lib/cli/translate-agent.js +450 -0
- package/lib/cli/translate-check.d.ts +17 -0
- package/lib/cli/translate-check.js +67 -0
- package/lib/cli/translate-checker.d.ts +58 -0
- package/lib/cli/translate-checker.js +112 -0
- package/lib/cli/translate-judge.d.ts +119 -0
- package/lib/cli/translate-judge.js +224 -0
- package/lib/cli/translate-limits.d.ts +43 -0
- package/lib/cli/translate-limits.js +55 -0
- package/lib/cli/translate-mask.d.ts +144 -0
- package/lib/cli/translate-mask.js +617 -0
- package/lib/cli/translate-models.d.ts +127 -0
- package/lib/cli/translate-models.js +189 -0
- package/lib/cli/translate-scratch.d.ts +142 -0
- package/lib/cli/translate-scratch.js +187 -0
- package/lib/cli/translate-terms.d.ts +22 -0
- package/lib/cli/translate-terms.js +33 -0
- package/lib/cli/translate.d.ts +15 -10
- package/lib/cli/translate.js +228 -185
- package/lib/eslint.js +22 -3
- package/lib/plugins/api/index.js +1 -1
- package/lib/plugins/api/types.d.ts +36 -1
- package/lib/plugins/global/components.d.ts +16 -0
- package/lib/plugins/global/components.js +16 -1
- package/lib/remark-lint/index.d.ts +20 -0
- package/lib/remark-lint/index.js +40 -0
- package/lib/remark-lint/no-unmatched-anchor.d.ts +10 -0
- package/lib/remark-lint/no-unmatched-anchor.js +13 -0
- package/lib/remark-lint/no-unopened-frontmatter.d.ts +2 -0
- package/lib/remark-lint/no-unopened-frontmatter.js +70 -0
- package/lib/remark-lint/no-unparsed-emphasis.d.ts +2 -0
- package/lib/remark-lint/no-unparsed-emphasis.js +53 -0
- package/lib/remark-lint/no-unresolved-api-ref.d.ts +40 -0
- package/lib/remark-lint/no-unresolved-api-ref.js +194 -0
- package/lib/remark-lint/rule-sets.d.ts +75 -0
- package/lib/remark-lint/rule-sets.js +120 -0
- package/lib/remark-lint/translation-parity/component-multiset.d.ts +17 -0
- package/lib/remark-lint/translation-parity/component-multiset.js +35 -0
- package/lib/remark-lint/translation-parity/echoed-source.d.ts +2 -0
- package/lib/remark-lint/translation-parity/echoed-source.js +37 -0
- package/lib/remark-lint/translation-parity/frontmatter-preservation.d.ts +2 -0
- package/lib/remark-lint/translation-parity/frontmatter-preservation.js +36 -0
- package/lib/remark-lint/translation-parity/heading-sequence.d.ts +12 -0
- package/lib/remark-lint/translation-parity/heading-sequence.js +25 -0
- package/lib/remark-lint/translation-parity/index.d.ts +24 -0
- package/lib/remark-lint/translation-parity/index.js +24 -0
- package/lib/remark-lint/translation-parity/jsx-attribute-parity.d.ts +14 -0
- package/lib/remark-lint/translation-parity/jsx-attribute-parity.js +47 -0
- package/lib/remark-lint/translation-parity/length-ratio.d.ts +2 -0
- package/lib/remark-lint/translation-parity/length-ratio.js +49 -0
- package/lib/remark-lint/translation-parity/link-isomorphism.d.ts +26 -0
- package/lib/remark-lint/translation-parity/link-isomorphism.js +45 -0
- package/lib/remark-lint/translation-parity/shared.d.ts +110 -0
- package/lib/remark-lint/translation-parity/shared.js +282 -0
- package/lib/remark-lint/translation-parity/terminology-adherence.d.ts +2 -0
- package/lib/remark-lint/translation-parity/terminology-adherence.js +67 -0
- package/lib/remark-lint/translation-parity/up-to-date.d.ts +11 -0
- package/lib/remark-lint/translation-parity/up-to-date.js +21 -0
- package/lib/remark-lint/translation-parity/url-residue.d.ts +2 -0
- package/lib/remark-lint/translation-parity/url-residue.js +46 -0
- package/lib/remarkrc.d.ts +1 -1
- package/lib/remarkrc.js +7 -34
- package/lib/runtime/api-paths.d.ts +20 -0
- package/lib/runtime/api-paths.js +29 -0
- package/lib/runtime/components/K8sAPI.d.ts +14 -1
- package/lib/runtime/components/K8sAPI.js +49 -10
- package/lib/runtime/components/K8sCrd.d.ts +1 -1
- package/lib/runtime/components/K8sPermissionTable.js +10 -5
- package/lib/runtime/components/OpenAPIPath.js +19 -2
- package/lib/runtime/components/_HeadingTitle.js +24 -6
- package/lib/runtime/components/_K8sAPIEndpoints.d.ts +8 -1
- package/lib/runtime/components/_K8sAPIEndpoints.js +27 -9
- package/lib/runtime/components/_K8sAPISchema.d.ts +9 -1
- package/lib/runtime/components/_K8sAPISchema.js +24 -6
- package/lib/runtime/components/_translation-policy.d.ts +23 -0
- package/lib/runtime/components/_translation-policy.js +32 -0
- package/lib/runtime/hooks/useTranslation.d.ts +1 -1
- package/lib/runtime/translation.d.ts +68 -0
- package/lib/runtime/translation.js +51 -0
- package/lib/runtime/utils.d.ts +24 -2
- package/lib/runtime/utils.js +87 -5
- package/lib/shared/constants.d.ts +9 -0
- package/lib/shared/constants.js +14 -0
- package/lib/types.d.ts +70 -0
- package/lib/utils/helpers.js +8 -2
- 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,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,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,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
|
+
});
|