@alauda/doom 2.5.3 → 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 +48 -5
- package/lib/plugins/api/index.js +1 -1
- package/lib/plugins/api/types.d.ts +36 -1
- package/lib/plugins/global/components.d.ts +18 -0
- package/lib/plugins/global/components.js +33 -0
- package/lib/plugins/global/index.js +2 -10
- 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,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
|
+
});
|
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
import type { Root } from 'mdast';
|
|
2
|
+
import type { VFile } from 'vfile';
|
|
3
|
+
/**
|
|
4
|
+
* Shared plumbing for the `translation-parity` rules.
|
|
5
|
+
*
|
|
6
|
+
* These are the only lint rules that need a *second* document: they compare a
|
|
7
|
+
* translation against the source it was made from. Everything they can say
|
|
8
|
+
* follows from that pairing, so getting the pairing right — and refusing to
|
|
9
|
+
* report anything when it is not right — is most of the work.
|
|
10
|
+
*
|
|
11
|
+
* The pairing itself is exact rather than heuristic: `doom translate` writes
|
|
12
|
+
* `sourceSHA` (the sha256 of the source file's bytes) into every translation it
|
|
13
|
+
* produces, so a translation and a source either belong together or do not.
|
|
14
|
+
* There is no "probably the same version" state to reason about.
|
|
15
|
+
*/
|
|
16
|
+
export interface TranslationPair {
|
|
17
|
+
/** language the document was translated from, e.g. `en` */
|
|
18
|
+
sourceLang: string;
|
|
19
|
+
/** language of the document being linted, e.g. `zh` */
|
|
20
|
+
targetLang: string;
|
|
21
|
+
/** path inside the locale directory, e.g. `install/installing.mdx` */
|
|
22
|
+
relativePath: string;
|
|
23
|
+
/** absolute path of the source document */
|
|
24
|
+
sourcePath: string;
|
|
25
|
+
sourceRaw: string;
|
|
26
|
+
sourceTree: Root;
|
|
27
|
+
sourceFrontmatter: Record<string, unknown>;
|
|
28
|
+
targetFrontmatter: Record<string, unknown>;
|
|
29
|
+
/**
|
|
30
|
+
* The document is copied rather than translated (`translate.copyOnlyDirectories`).
|
|
31
|
+
* Its structure must still match its source, but it is *supposed* to still be
|
|
32
|
+
* in the source language — so asking whether it reads as Chinese asks the
|
|
33
|
+
* wrong question of the right file.
|
|
34
|
+
*/
|
|
35
|
+
isCopyOnly: boolean;
|
|
36
|
+
}
|
|
37
|
+
export type TranslationStatus =
|
|
38
|
+
/** not under the docs root, or is itself the source language */
|
|
39
|
+
{
|
|
40
|
+
kind: 'not-a-translation';
|
|
41
|
+
}
|
|
42
|
+
/**
|
|
43
|
+
* No `sourceSHA`: the document is maintained by hand — the documented escape
|
|
44
|
+
* hatch is `i18n.disableAutoTranslation` in the source's frontmatter. Nothing
|
|
45
|
+
* here can say anything about it.
|
|
46
|
+
*/
|
|
47
|
+
| {
|
|
48
|
+
kind: 'unmanaged';
|
|
49
|
+
} | {
|
|
50
|
+
kind: 'source-missing';
|
|
51
|
+
sourcePath: string;
|
|
52
|
+
} | {
|
|
53
|
+
kind: 'stale';
|
|
54
|
+
sourcePath: string;
|
|
55
|
+
expected: string;
|
|
56
|
+
actual: string;
|
|
57
|
+
} | {
|
|
58
|
+
kind: 'current';
|
|
59
|
+
pair: TranslationPair;
|
|
60
|
+
};
|
|
61
|
+
/**
|
|
62
|
+
* Works out whether the document being linted is a translation, and if so
|
|
63
|
+
* whether it still corresponds to its source.
|
|
64
|
+
*/
|
|
65
|
+
export declare const resolveTranslation: (tree: Root, vfile: VFile) => Promise<TranslationStatus>;
|
|
66
|
+
/** Resolves the pair, or nothing at all when there is nothing to compare. */
|
|
67
|
+
export declare const currentPair: (tree: Root, vfile: VFile) => Promise<TranslationPair | undefined>;
|
|
68
|
+
/** Open tags of every component used in a document, counted by name. */
|
|
69
|
+
export declare const collectComponents: (tree: Root) => Map<string, number>;
|
|
70
|
+
/** The document's heading levels, in order. */
|
|
71
|
+
export declare const collectHeadingDepths: (tree: Root) => number[];
|
|
72
|
+
/**
|
|
73
|
+
* Every JSX attribute that carries a literal string value, keyed
|
|
74
|
+
* `Component.attribute`. Expression values are read through to their source
|
|
75
|
+
* text, which is what has to stay byte-identical.
|
|
76
|
+
*/
|
|
77
|
+
export declare const collectJsxAttributes: (tree: Root) => Map<string, string[]>;
|
|
78
|
+
/**
|
|
79
|
+
* Resolves a link the way the site does — against the position of the document
|
|
80
|
+
* that holds it — and then drops the language segment.
|
|
81
|
+
*
|
|
82
|
+
* This is what makes source and translation comparable at all. A translation's
|
|
83
|
+
* links legitimately differ from the source's as *written*: assets are rewritten
|
|
84
|
+
* to point back into the source-language tree (`../../../en/…/x.png`) because
|
|
85
|
+
* they are not copied per language. Resolved and de-localised, both spellings
|
|
86
|
+
* name the same file, so anything still different is a real difference.
|
|
87
|
+
*/
|
|
88
|
+
export declare const resolveLinkTarget: (url: string, docDirInRoot: string) => string;
|
|
89
|
+
/**
|
|
90
|
+
* Every link target a document points at: markdown links and images, reference
|
|
91
|
+
* definitions, `href`/`src` on components, and the same inside raw HTML.
|
|
92
|
+
*/
|
|
93
|
+
export declare const collectLinkTargets: (tree: Root, docDirInRoot: string) => string[];
|
|
94
|
+
/** Multiset difference, reported as what is missing and what is extra. */
|
|
95
|
+
export declare const diffMultiset: (expected: readonly string[], actual: readonly string[]) => {
|
|
96
|
+
missing: string[];
|
|
97
|
+
extra: string[];
|
|
98
|
+
};
|
|
99
|
+
/**
|
|
100
|
+
* The document's prose — the text a reader reads, and the only text a
|
|
101
|
+
* translation is supposed to change.
|
|
102
|
+
*
|
|
103
|
+
* Code, inline code and component attributes are excluded because they are not
|
|
104
|
+
* prose: counting them would make a page full of `kubectl` commands look
|
|
105
|
+
* untranslated, and would make a translated page look longer or shorter than it
|
|
106
|
+
* is for reasons that have nothing to do with the translation.
|
|
107
|
+
*/
|
|
108
|
+
export declare const collectProseText: (tree: Root) => string;
|
|
109
|
+
/** The directory a document sits in, relative to the docs root, in posix form. */
|
|
110
|
+
export declare const docDirInRoot: (targetLang: string, relativePath: string) => string;
|
|
@@ -0,0 +1,282 @@
|
|
|
1
|
+
import crypto from 'node:crypto';
|
|
2
|
+
import fs from 'node:fs/promises';
|
|
3
|
+
import path from 'node:path';
|
|
4
|
+
import picomatch from 'picomatch';
|
|
5
|
+
import { visit } from 'unist-util-visit';
|
|
6
|
+
import { parse as parseYaml } from 'yaml';
|
|
7
|
+
import { escapeMarkdownHeadingIds } from "../../cli/helpers.js";
|
|
8
|
+
import { mdProcessor, mdxProcessor } from "../../plugins/index.js";
|
|
9
|
+
import { DEFAULT_COPY_ONLY_DIRECTORIES, SUPPORTED_LANGUAGES, } from "../../shared/index.js";
|
|
10
|
+
import { getConfig } from "../utils.js";
|
|
11
|
+
const matcherCache = new Map();
|
|
12
|
+
/** Memoised, because it is asked once per document and the patterns never change. */
|
|
13
|
+
const isCopyOnlyMatcher = (patterns) => {
|
|
14
|
+
const key = patterns.join('\u0000');
|
|
15
|
+
let matcher = matcherCache.get(key);
|
|
16
|
+
if (!matcher) {
|
|
17
|
+
// Same matcher tinyglobby uses to select these files in `doom translate`,
|
|
18
|
+
// so what is checked here is exactly what is copied there.
|
|
19
|
+
matcher = picomatch([...patterns]);
|
|
20
|
+
matcherCache.set(key, matcher);
|
|
21
|
+
}
|
|
22
|
+
return matcher;
|
|
23
|
+
};
|
|
24
|
+
const frontmatterOf = (tree) => {
|
|
25
|
+
const first = tree.children.at(0);
|
|
26
|
+
if (first?.type !== 'yaml') {
|
|
27
|
+
return {};
|
|
28
|
+
}
|
|
29
|
+
return parseYaml(first.value) ?? {};
|
|
30
|
+
};
|
|
31
|
+
const sourceCache = new Map();
|
|
32
|
+
const loadSource = async (sourcePath) => {
|
|
33
|
+
const raw = await fs.readFile(sourcePath, 'utf8');
|
|
34
|
+
const sha = crypto.createHash('sha256').update(raw).digest('hex');
|
|
35
|
+
const cached = sourceCache.get(sourcePath);
|
|
36
|
+
if (cached?.sha === sha) {
|
|
37
|
+
return cached;
|
|
38
|
+
}
|
|
39
|
+
const processor = sourcePath.endsWith('.mdx') ? mdxProcessor : mdProcessor;
|
|
40
|
+
// The same escaping `doom translate` applies before parsing: without it a
|
|
41
|
+
// custom heading anchor is an MDX expression and the parse fails outright.
|
|
42
|
+
const entry = {
|
|
43
|
+
sha,
|
|
44
|
+
raw,
|
|
45
|
+
tree: processor.parse(escapeMarkdownHeadingIds(raw)),
|
|
46
|
+
};
|
|
47
|
+
sourceCache.set(sourcePath, entry);
|
|
48
|
+
return entry;
|
|
49
|
+
};
|
|
50
|
+
/**
|
|
51
|
+
* Works out whether the document being linted is a translation, and if so
|
|
52
|
+
* whether it still corresponds to its source.
|
|
53
|
+
*/
|
|
54
|
+
export const resolveTranslation = async (tree, vfile) => {
|
|
55
|
+
const { config } = await getConfig();
|
|
56
|
+
const root = config.root;
|
|
57
|
+
if (!root || !vfile.path) {
|
|
58
|
+
return { kind: 'not-a-translation' };
|
|
59
|
+
}
|
|
60
|
+
const relative = path.relative(root, vfile.path);
|
|
61
|
+
if (relative.startsWith('..')) {
|
|
62
|
+
return { kind: 'not-a-translation' };
|
|
63
|
+
}
|
|
64
|
+
const segments = relative.split(path.sep);
|
|
65
|
+
const targetLang = segments[0];
|
|
66
|
+
const sourceLang = config.lang ?? 'en';
|
|
67
|
+
if (segments.length < 2 ||
|
|
68
|
+
targetLang === sourceLang ||
|
|
69
|
+
!SUPPORTED_LANGUAGES.includes(targetLang)) {
|
|
70
|
+
return { kind: 'not-a-translation' };
|
|
71
|
+
}
|
|
72
|
+
const targetFrontmatter = frontmatterOf(tree);
|
|
73
|
+
const declared = targetFrontmatter.sourceSHA;
|
|
74
|
+
if (typeof declared !== 'string') {
|
|
75
|
+
return { kind: 'unmanaged' };
|
|
76
|
+
}
|
|
77
|
+
const relativePath = segments.slice(1).join('/');
|
|
78
|
+
const sourcePath = path.join(root, sourceLang, ...segments.slice(1));
|
|
79
|
+
let source;
|
|
80
|
+
try {
|
|
81
|
+
source = await loadSource(sourcePath);
|
|
82
|
+
}
|
|
83
|
+
catch {
|
|
84
|
+
return { kind: 'source-missing', sourcePath };
|
|
85
|
+
}
|
|
86
|
+
if (source.sha !== declared) {
|
|
87
|
+
return {
|
|
88
|
+
kind: 'stale',
|
|
89
|
+
sourcePath,
|
|
90
|
+
expected: source.sha,
|
|
91
|
+
actual: declared,
|
|
92
|
+
};
|
|
93
|
+
}
|
|
94
|
+
return {
|
|
95
|
+
kind: 'current',
|
|
96
|
+
pair: {
|
|
97
|
+
sourceLang,
|
|
98
|
+
targetLang,
|
|
99
|
+
relativePath,
|
|
100
|
+
sourcePath,
|
|
101
|
+
sourceRaw: source.raw,
|
|
102
|
+
sourceTree: source.tree,
|
|
103
|
+
sourceFrontmatter: frontmatterOf(source.tree),
|
|
104
|
+
targetFrontmatter,
|
|
105
|
+
isCopyOnly: isCopyOnlyMatcher(config.translate?.copyOnlyDirectories ?? DEFAULT_COPY_ONLY_DIRECTORIES)(relativePath),
|
|
106
|
+
},
|
|
107
|
+
};
|
|
108
|
+
};
|
|
109
|
+
/** Resolves the pair, or nothing at all when there is nothing to compare. */
|
|
110
|
+
export const currentPair = async (tree, vfile) => {
|
|
111
|
+
const status = await resolveTranslation(tree, vfile);
|
|
112
|
+
return status.kind === 'current' ? status.pair : undefined;
|
|
113
|
+
};
|
|
114
|
+
// ---------------------------------------------------------------------------
|
|
115
|
+
// Collectors — everything below reads a tree and returns something comparable.
|
|
116
|
+
// ---------------------------------------------------------------------------
|
|
117
|
+
const isJsxElement = (node) => node.type === 'mdxJsxFlowElement' || node.type === 'mdxJsxTextElement';
|
|
118
|
+
/** Open tags of every component used in a document, counted by name. */
|
|
119
|
+
export const collectComponents = (tree) => {
|
|
120
|
+
const counts = new Map();
|
|
121
|
+
visit(tree, (node) => {
|
|
122
|
+
if (isJsxElement(node) && node.name) {
|
|
123
|
+
counts.set(node.name, (counts.get(node.name) ?? 0) + 1);
|
|
124
|
+
}
|
|
125
|
+
});
|
|
126
|
+
return counts;
|
|
127
|
+
};
|
|
128
|
+
/** The document's heading levels, in order. */
|
|
129
|
+
export const collectHeadingDepths = (tree) => {
|
|
130
|
+
const depths = [];
|
|
131
|
+
visit(tree, 'heading', (node) => {
|
|
132
|
+
depths.push(node.depth);
|
|
133
|
+
});
|
|
134
|
+
return depths;
|
|
135
|
+
};
|
|
136
|
+
/**
|
|
137
|
+
* Every JSX attribute that carries a literal string value, keyed
|
|
138
|
+
* `Component.attribute`. Expression values are read through to their source
|
|
139
|
+
* text, which is what has to stay byte-identical.
|
|
140
|
+
*/
|
|
141
|
+
export const collectJsxAttributes = (tree) => {
|
|
142
|
+
const values = new Map();
|
|
143
|
+
visit(tree, (node) => {
|
|
144
|
+
if (!isJsxElement(node) || !node.name) {
|
|
145
|
+
return;
|
|
146
|
+
}
|
|
147
|
+
for (const attr of node.attributes) {
|
|
148
|
+
if (attr.type === 'mdxJsxExpressionAttribute') {
|
|
149
|
+
push(values, `${node.name}.{...}`, attr.value);
|
|
150
|
+
continue;
|
|
151
|
+
}
|
|
152
|
+
if (attr.value == null) {
|
|
153
|
+
continue;
|
|
154
|
+
}
|
|
155
|
+
push(values, `${node.name}.${attr.name}`, typeof attr.value === 'string' ? attr.value : attr.value.value);
|
|
156
|
+
}
|
|
157
|
+
});
|
|
158
|
+
return values;
|
|
159
|
+
};
|
|
160
|
+
const push = (map, key, value) => {
|
|
161
|
+
const list = map.get(key);
|
|
162
|
+
if (list) {
|
|
163
|
+
list.push(value);
|
|
164
|
+
}
|
|
165
|
+
else {
|
|
166
|
+
map.set(key, [value]);
|
|
167
|
+
}
|
|
168
|
+
};
|
|
169
|
+
const EXTERNAL_URL = /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i;
|
|
170
|
+
const LOCALE_PREFIX = new RegExp(`^/(?:${SUPPORTED_LANGUAGES.join('|')})(?=/|$)`);
|
|
171
|
+
/**
|
|
172
|
+
* Resolves a link the way the site does — against the position of the document
|
|
173
|
+
* that holds it — and then drops the language segment.
|
|
174
|
+
*
|
|
175
|
+
* This is what makes source and translation comparable at all. A translation's
|
|
176
|
+
* links legitimately differ from the source's as *written*: assets are rewritten
|
|
177
|
+
* to point back into the source-language tree (`../../../en/…/x.png`) because
|
|
178
|
+
* they are not copied per language. Resolved and de-localised, both spellings
|
|
179
|
+
* name the same file, so anything still different is a real difference.
|
|
180
|
+
*/
|
|
181
|
+
export const resolveLinkTarget = (url, docDirInRoot) => {
|
|
182
|
+
const trimmed = url.trim();
|
|
183
|
+
if (!trimmed || EXTERNAL_URL.test(trimmed) || trimmed.startsWith('#')) {
|
|
184
|
+
return trimmed;
|
|
185
|
+
}
|
|
186
|
+
const hashAt = trimmed.indexOf('#');
|
|
187
|
+
const target = hashAt < 0 ? trimmed : trimmed.slice(0, hashAt);
|
|
188
|
+
const hash = hashAt < 0 ? '' : trimmed.slice(hashAt);
|
|
189
|
+
if (!target) {
|
|
190
|
+
return trimmed;
|
|
191
|
+
}
|
|
192
|
+
const absolute = target.startsWith('/')
|
|
193
|
+
? path.posix.normalize(target)
|
|
194
|
+
: path.posix.resolve(`/${docDirInRoot}`, target);
|
|
195
|
+
return absolute.replace(LOCALE_PREFIX, '') + hash;
|
|
196
|
+
};
|
|
197
|
+
const LINK_ATTRIBUTES = new Set(['href', 'src']);
|
|
198
|
+
const HTML_LINK_ATTRIBUTE = /\b(?:href|src)\s*=\s*(["'])(.*?)\1/gi;
|
|
199
|
+
/**
|
|
200
|
+
* Every link target a document points at: markdown links and images, reference
|
|
201
|
+
* definitions, `href`/`src` on components, and the same inside raw HTML.
|
|
202
|
+
*/
|
|
203
|
+
export const collectLinkTargets = (tree, docDirInRoot) => {
|
|
204
|
+
const targets = [];
|
|
205
|
+
const add = (url) => {
|
|
206
|
+
const resolved = resolveLinkTarget(url, docDirInRoot);
|
|
207
|
+
if (resolved) {
|
|
208
|
+
targets.push(resolved);
|
|
209
|
+
}
|
|
210
|
+
};
|
|
211
|
+
visit(tree, (node) => {
|
|
212
|
+
switch (node.type) {
|
|
213
|
+
case 'link':
|
|
214
|
+
case 'image':
|
|
215
|
+
case 'definition': {
|
|
216
|
+
add(node.url);
|
|
217
|
+
return;
|
|
218
|
+
}
|
|
219
|
+
case 'html': {
|
|
220
|
+
for (const [, , value] of node.value.matchAll(HTML_LINK_ATTRIBUTE)) {
|
|
221
|
+
add(value);
|
|
222
|
+
}
|
|
223
|
+
return;
|
|
224
|
+
}
|
|
225
|
+
default: {
|
|
226
|
+
if (!isJsxElement(node)) {
|
|
227
|
+
return;
|
|
228
|
+
}
|
|
229
|
+
for (const attr of node.attributes) {
|
|
230
|
+
if (attr.type === 'mdxJsxAttribute' &&
|
|
231
|
+
LINK_ATTRIBUTES.has(attr.name) &&
|
|
232
|
+
typeof attr.value === 'string') {
|
|
233
|
+
add(attr.value);
|
|
234
|
+
}
|
|
235
|
+
}
|
|
236
|
+
}
|
|
237
|
+
}
|
|
238
|
+
});
|
|
239
|
+
return targets;
|
|
240
|
+
};
|
|
241
|
+
/** Multiset difference, reported as what is missing and what is extra. */
|
|
242
|
+
export const diffMultiset = (expected, actual) => {
|
|
243
|
+
const counts = new Map();
|
|
244
|
+
for (const value of expected) {
|
|
245
|
+
counts.set(value, (counts.get(value) ?? 0) + 1);
|
|
246
|
+
}
|
|
247
|
+
for (const value of actual) {
|
|
248
|
+
counts.set(value, (counts.get(value) ?? 0) - 1);
|
|
249
|
+
}
|
|
250
|
+
const missing = [];
|
|
251
|
+
const extra = [];
|
|
252
|
+
for (const [value, delta] of counts) {
|
|
253
|
+
for (let i = 0; i < delta; i++) {
|
|
254
|
+
missing.push(value);
|
|
255
|
+
}
|
|
256
|
+
for (let i = 0; i < -delta; i++) {
|
|
257
|
+
extra.push(value);
|
|
258
|
+
}
|
|
259
|
+
}
|
|
260
|
+
return { missing: missing.sort(), extra: extra.sort() };
|
|
261
|
+
};
|
|
262
|
+
/**
|
|
263
|
+
* The document's prose — the text a reader reads, and the only text a
|
|
264
|
+
* translation is supposed to change.
|
|
265
|
+
*
|
|
266
|
+
* Code, inline code and component attributes are excluded because they are not
|
|
267
|
+
* prose: counting them would make a page full of `kubectl` commands look
|
|
268
|
+
* untranslated, and would make a translated page look longer or shorter than it
|
|
269
|
+
* is for reasons that have nothing to do with the translation.
|
|
270
|
+
*/
|
|
271
|
+
export const collectProseText = (tree) => {
|
|
272
|
+
const parts = [];
|
|
273
|
+
visit(tree, 'text', (node) => {
|
|
274
|
+
parts.push(node.value);
|
|
275
|
+
});
|
|
276
|
+
return parts.join(' ');
|
|
277
|
+
};
|
|
278
|
+
/** The directory a document sits in, relative to the docs root, in posix form. */
|
|
279
|
+
export const docDirInRoot = (targetLang, relativePath) => {
|
|
280
|
+
const dir = path.posix.dirname(`${targetLang}/${relativePath}`);
|
|
281
|
+
return dir === '.' ? '' : dir;
|
|
282
|
+
};
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
import { lintRule } from 'unified-lint-rule';
|
|
2
|
+
import { parseTerms } from "../../cli/helpers.js";
|
|
3
|
+
import { collectProseText, currentPair } from "./shared.js";
|
|
4
|
+
/**
|
|
5
|
+
* A translation uses the agreed word for an agreed term.
|
|
6
|
+
*
|
|
7
|
+
* The terminology table is already resolved and injected into the translator's
|
|
8
|
+
* prompt for every document, and nothing has ever checked whether the output
|
|
9
|
+
* used it. Turning that into a check costs nothing: same table, read the same
|
|
10
|
+
* way.
|
|
11
|
+
*
|
|
12
|
+
* **Not registered in the default rule set**, and this is why. Run over 1050
|
|
13
|
+
* real pairs it reported 490 problems on a corpus that is substantially
|
|
14
|
+
* correct, because the table is a glossary of preferences rather than a set of
|
|
15
|
+
* invariants: `Application` → `原生应用` fired 124 times, `view` → `视图` 84,
|
|
16
|
+
* `log` → `日志` 39, `NodePort` → `主机端口` 8. Those source words are ordinary
|
|
17
|
+
* English, and their agreed rendering applies to the product feature, not to
|
|
18
|
+
* every sentence that happens to contain the word. A rule that fires 490 times
|
|
19
|
+
* on a healthy corpus does not enforce terminology; it teaches people to
|
|
20
|
+
* disregard the gate.
|
|
21
|
+
*
|
|
22
|
+
* Making it enforceable is an upstream change: the table needs to say which
|
|
23
|
+
* entries are invariants. Until then this is available to run deliberately —
|
|
24
|
+
* `doom lint` with the rule switched on — and is not part of any gate.
|
|
25
|
+
*
|
|
26
|
+
* Matching happens on prose only. `Alauda` inside `security.alauda.io` is an
|
|
27
|
+
* API group, not the company, and a check that cannot tell the difference is a
|
|
28
|
+
* check nobody would keep switched on.
|
|
29
|
+
*/
|
|
30
|
+
const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
|
|
31
|
+
let termsFailureReported = false;
|
|
32
|
+
export const translationTerminologyAdherence = lintRule('doom-lint:translation-terminology-adherence', async (tree, vfile) => {
|
|
33
|
+
const pair = await currentPair(tree, vfile);
|
|
34
|
+
if (!pair || pair.isCopyOnly) {
|
|
35
|
+
return;
|
|
36
|
+
}
|
|
37
|
+
let terms;
|
|
38
|
+
try {
|
|
39
|
+
terms = await parseTerms();
|
|
40
|
+
}
|
|
41
|
+
catch (error) {
|
|
42
|
+
// A check that cannot run must say so. Once per process: the table is
|
|
43
|
+
// fetched once, and one unreadable table is one problem, not nine hundred.
|
|
44
|
+
if (!termsFailureReported) {
|
|
45
|
+
termsFailureReported = true;
|
|
46
|
+
vfile.message(`Terminology could not be read, so terminology adherence went unchecked in this run: ${error instanceof Error ? error.message : String(error)}`, tree);
|
|
47
|
+
}
|
|
48
|
+
return;
|
|
49
|
+
}
|
|
50
|
+
const sourceProse = collectProseText(pair.sourceTree);
|
|
51
|
+
const targetProse = collectProseText(tree).toLowerCase();
|
|
52
|
+
for (const term of terms) {
|
|
53
|
+
const source = term[pair.sourceLang];
|
|
54
|
+
const target = term[pair.targetLang];
|
|
55
|
+
if (!source || !target) {
|
|
56
|
+
continue;
|
|
57
|
+
}
|
|
58
|
+
const inSource = new RegExp(`\\b${escapeRegExp(source)}\\b`, 'i');
|
|
59
|
+
if (!inSource.test(sourceProse)) {
|
|
60
|
+
continue;
|
|
61
|
+
}
|
|
62
|
+
if (targetProse.includes(target.toLowerCase())) {
|
|
63
|
+
continue;
|
|
64
|
+
}
|
|
65
|
+
vfile.message(`Translation does not use the agreed term for \`${source}\`: expected \`${target}\` somewhere in the prose.`, tree);
|
|
66
|
+
}
|
|
67
|
+
});
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
import type { Root } from 'mdast';
|
|
2
|
+
/**
|
|
3
|
+
* A translation must correspond to the source it declares.
|
|
4
|
+
*
|
|
5
|
+
* Every other `translation-parity` rule compares two documents, and every one of
|
|
6
|
+
* them is meaningless — noisy, or falsely quiet — if the two are different
|
|
7
|
+
* versions of the same page. So they all stand down unless this one is
|
|
8
|
+
* satisfied, and this one says so out loud rather than letting them skip in
|
|
9
|
+
* silence.
|
|
10
|
+
*/
|
|
11
|
+
export declare const translationUpToDate: import("unified-lint-rule").Plugin<Root, unknown>;
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
import { lintRule } from 'unified-lint-rule';
|
|
2
|
+
import { resolveTranslation } from "./shared.js";
|
|
3
|
+
/**
|
|
4
|
+
* A translation must correspond to the source it declares.
|
|
5
|
+
*
|
|
6
|
+
* Every other `translation-parity` rule compares two documents, and every one of
|
|
7
|
+
* them is meaningless — noisy, or falsely quiet — if the two are different
|
|
8
|
+
* versions of the same page. So they all stand down unless this one is
|
|
9
|
+
* satisfied, and this one says so out loud rather than letting them skip in
|
|
10
|
+
* silence.
|
|
11
|
+
*/
|
|
12
|
+
export const translationUpToDate = lintRule('doom-lint:translation-up-to-date', async (tree, vfile) => {
|
|
13
|
+
const status = await resolveTranslation(tree, vfile);
|
|
14
|
+
if (status.kind === 'stale') {
|
|
15
|
+
vfile.message(`Translation is out of date: its \`sourceSHA\` names a version of \`${status.sourcePath}\` that no longer exists. Re-run \`doom translate\`; until then no translation check can say anything about this file.`, tree);
|
|
16
|
+
return;
|
|
17
|
+
}
|
|
18
|
+
if (status.kind === 'source-missing') {
|
|
19
|
+
vfile.message(`Translation has no source: nothing exists at \`${status.sourcePath}\`. Either the source page was removed and this one should go too, or it is in the wrong place.`, tree);
|
|
20
|
+
}
|
|
21
|
+
});
|