@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.
- 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 +19 -2
- 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 +73 -0
- package/lib/remark-lint/rule-sets.js +114 -0
- package/lib/remark-lint/syntax-plugins.d.ts +32 -0
- package/lib/remark-lint/syntax-plugins.js +46 -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 +34 -0
- package/lib/remark-lint/translation-parity/link-isomorphism.js +81 -0
- package/lib/remark-lint/translation-parity/shared.d.ts +110 -0
- package/lib/remark-lint/translation-parity/shared.js +286 -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 +3 -0
- package/lib/remark-lint/translation-parity/url-residue.js +67 -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,81 @@
|
|
|
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 bare URL ends where markdown says it ends, and markdown does not know
|
|
9
|
+
* about Chinese sentence punctuation.
|
|
10
|
+
*
|
|
11
|
+
* GFM closes an autolink literal at whitespace and drops *ASCII* trailing
|
|
12
|
+
* punctuation, so `see http://h:8080.` links to `http://h:8080`. A full-width
|
|
13
|
+
* stop is not ASCII: it is absorbed, and `例如 http://h:8080。` links to
|
|
14
|
+
* `http://h:8080。`, an address that does not exist. The translator writes
|
|
15
|
+
* correct Chinese and gets a broken link for it — and the two messages it used
|
|
16
|
+
* to get, "lost this target" and "points at that one", never said which of the
|
|
17
|
+
* two spellings was the one to change, so the repair loop could only guess.
|
|
18
|
+
*
|
|
19
|
+
* Only a non-ASCII suffix is read this way. `https://x.com` becoming
|
|
20
|
+
* `https://x.com/docs` is also a prefix, and that one is a real retarget.
|
|
21
|
+
*/
|
|
22
|
+
const isAbsorbedSuffix = (suffix) => suffix.length > 0 && suffix.codePointAt(0) > 0x7f;
|
|
23
|
+
export const partitionAbsorbed = (missing, extra) => {
|
|
24
|
+
const unmatched = [...extra];
|
|
25
|
+
const lost = [];
|
|
26
|
+
const absorbed = [];
|
|
27
|
+
for (const target of missing) {
|
|
28
|
+
const index = unmatched.findIndex((candidate) => candidate.startsWith(target) &&
|
|
29
|
+
isAbsorbedSuffix(candidate.slice(target.length)));
|
|
30
|
+
if (index === -1) {
|
|
31
|
+
lost.push(target);
|
|
32
|
+
continue;
|
|
33
|
+
}
|
|
34
|
+
absorbed.push({ target, suffix: unmatched[index].slice(target.length) });
|
|
35
|
+
unmatched.splice(index, 1);
|
|
36
|
+
}
|
|
37
|
+
return { absorbed, lost, unmatched };
|
|
38
|
+
};
|
|
39
|
+
/**
|
|
40
|
+
* A translation points at exactly the same places its source points at.
|
|
41
|
+
*
|
|
42
|
+
* Not "its links resolve" — that is a much weaker property, and it is the one
|
|
43
|
+
* the build happens to check. A link can be rewritten into a different, still
|
|
44
|
+
* existing page and the build stays green while the reader is sent somewhere
|
|
45
|
+
* else. Every link is therefore resolved against the position of the document
|
|
46
|
+
* holding it and stripped of its language segment, and the resulting multisets
|
|
47
|
+
* must match.
|
|
48
|
+
*
|
|
49
|
+
* Resolving is what makes the comparison possible: a translation's asset links
|
|
50
|
+
* legitimately read `../../../en/networking/x.png` where the source reads
|
|
51
|
+
* `./x.png`, because assets are not copied per language. Both name the same
|
|
52
|
+
* file, so they compare equal — while every corruption measured on this corpus
|
|
53
|
+
* does not:
|
|
54
|
+
*
|
|
55
|
+
* - a `<ExternalSiteLink … href="/global/install.html" />` flattened into
|
|
56
|
+
* `[…](../global/install.html)`;
|
|
57
|
+
* - `../virtualization/virtualization/virtual_machine/…` collapsed into
|
|
58
|
+
* `../virtualization/virtualization_virtual_machine/…`;
|
|
59
|
+
* - `../global_dr.mdx` rewritten as `../global.dr.mdx`;
|
|
60
|
+
* - `how_to/` rewritten as `how-to/`;
|
|
61
|
+
* - the same link generated twice.
|
|
62
|
+
*/
|
|
63
|
+
export const translationLinkIsomorphism = lintRule('doom-lint:translation-link-isomorphism', async (tree, vfile) => {
|
|
64
|
+
const pair = await currentPair(tree, vfile);
|
|
65
|
+
if (!pair) {
|
|
66
|
+
return;
|
|
67
|
+
}
|
|
68
|
+
const expected = collectLinkTargets(pair.sourceTree, docDirInRoot(pair.sourceLang, pair.relativePath));
|
|
69
|
+
const actual = collectLinkTargets(tree, docDirInRoot(pair.targetLang, pair.relativePath));
|
|
70
|
+
const { missing, extra } = diffMultiset(expected, actual);
|
|
71
|
+
const { absorbed, lost, unmatched } = partitionAbsorbed(missing, extra);
|
|
72
|
+
for (const { target, suffix } of absorbed) {
|
|
73
|
+
vfile.message(`Translation link \`${target}${suffix}\` swallowed the \`${suffix}\` that follows it: a bare URL runs on until a space, and markdown only leaves out trailing ASCII punctuation. Write it as \`[${target}](${target})\` so the punctuation stays outside the link.`, tree);
|
|
74
|
+
}
|
|
75
|
+
if (lost.length) {
|
|
76
|
+
vfile.message(`Translation lost ${lost.length} link target(s) the source has: ${preview(lost)}.`, tree);
|
|
77
|
+
}
|
|
78
|
+
if (unmatched.length) {
|
|
79
|
+
vfile.message(`Translation points at ${unmatched.length} target(s) the source does not: ${preview(unmatched)}.`, tree);
|
|
80
|
+
}
|
|
81
|
+
});
|
|
@@ -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,286 @@
|
|
|
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 { DEFAULT_COPY_ONLY_DIRECTORIES, SUPPORTED_LANGUAGES, } from "../../shared/index.js";
|
|
9
|
+
import { syntaxProcessor } from "../syntax-plugins.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
|
+
// The same syntax stack the document being linted came through: a
|
|
40
|
+
// comparison between two differently-parsed trees measures the parsers.
|
|
41
|
+
const processor = sourcePath.endsWith('.mdx')
|
|
42
|
+
? syntaxProcessor.mdx
|
|
43
|
+
: syntaxProcessor.md;
|
|
44
|
+
// The same escaping `doom translate` applies before parsing: without it a
|
|
45
|
+
// custom heading anchor is an MDX expression and the parse fails outright.
|
|
46
|
+
const entry = {
|
|
47
|
+
sha,
|
|
48
|
+
raw,
|
|
49
|
+
tree: processor.parse(escapeMarkdownHeadingIds(raw)),
|
|
50
|
+
};
|
|
51
|
+
sourceCache.set(sourcePath, entry);
|
|
52
|
+
return entry;
|
|
53
|
+
};
|
|
54
|
+
/**
|
|
55
|
+
* Works out whether the document being linted is a translation, and if so
|
|
56
|
+
* whether it still corresponds to its source.
|
|
57
|
+
*/
|
|
58
|
+
export const resolveTranslation = async (tree, vfile) => {
|
|
59
|
+
const { config } = await getConfig();
|
|
60
|
+
const root = config.root;
|
|
61
|
+
if (!root || !vfile.path) {
|
|
62
|
+
return { kind: 'not-a-translation' };
|
|
63
|
+
}
|
|
64
|
+
const relative = path.relative(root, vfile.path);
|
|
65
|
+
if (relative.startsWith('..')) {
|
|
66
|
+
return { kind: 'not-a-translation' };
|
|
67
|
+
}
|
|
68
|
+
const segments = relative.split(path.sep);
|
|
69
|
+
const targetLang = segments[0];
|
|
70
|
+
const sourceLang = config.lang ?? 'en';
|
|
71
|
+
if (segments.length < 2 ||
|
|
72
|
+
targetLang === sourceLang ||
|
|
73
|
+
!SUPPORTED_LANGUAGES.includes(targetLang)) {
|
|
74
|
+
return { kind: 'not-a-translation' };
|
|
75
|
+
}
|
|
76
|
+
const targetFrontmatter = frontmatterOf(tree);
|
|
77
|
+
const declared = targetFrontmatter.sourceSHA;
|
|
78
|
+
if (typeof declared !== 'string') {
|
|
79
|
+
return { kind: 'unmanaged' };
|
|
80
|
+
}
|
|
81
|
+
const relativePath = segments.slice(1).join('/');
|
|
82
|
+
const sourcePath = path.join(root, sourceLang, ...segments.slice(1));
|
|
83
|
+
let source;
|
|
84
|
+
try {
|
|
85
|
+
source = await loadSource(sourcePath);
|
|
86
|
+
}
|
|
87
|
+
catch {
|
|
88
|
+
return { kind: 'source-missing', sourcePath };
|
|
89
|
+
}
|
|
90
|
+
if (source.sha !== declared) {
|
|
91
|
+
return {
|
|
92
|
+
kind: 'stale',
|
|
93
|
+
sourcePath,
|
|
94
|
+
expected: source.sha,
|
|
95
|
+
actual: declared,
|
|
96
|
+
};
|
|
97
|
+
}
|
|
98
|
+
return {
|
|
99
|
+
kind: 'current',
|
|
100
|
+
pair: {
|
|
101
|
+
sourceLang,
|
|
102
|
+
targetLang,
|
|
103
|
+
relativePath,
|
|
104
|
+
sourcePath,
|
|
105
|
+
sourceRaw: source.raw,
|
|
106
|
+
sourceTree: source.tree,
|
|
107
|
+
sourceFrontmatter: frontmatterOf(source.tree),
|
|
108
|
+
targetFrontmatter,
|
|
109
|
+
isCopyOnly: isCopyOnlyMatcher(config.translate?.copyOnlyDirectories ?? DEFAULT_COPY_ONLY_DIRECTORIES)(relativePath),
|
|
110
|
+
},
|
|
111
|
+
};
|
|
112
|
+
};
|
|
113
|
+
/** Resolves the pair, or nothing at all when there is nothing to compare. */
|
|
114
|
+
export const currentPair = async (tree, vfile) => {
|
|
115
|
+
const status = await resolveTranslation(tree, vfile);
|
|
116
|
+
return status.kind === 'current' ? status.pair : undefined;
|
|
117
|
+
};
|
|
118
|
+
// ---------------------------------------------------------------------------
|
|
119
|
+
// Collectors — everything below reads a tree and returns something comparable.
|
|
120
|
+
// ---------------------------------------------------------------------------
|
|
121
|
+
const isJsxElement = (node) => node.type === 'mdxJsxFlowElement' || node.type === 'mdxJsxTextElement';
|
|
122
|
+
/** Open tags of every component used in a document, counted by name. */
|
|
123
|
+
export const collectComponents = (tree) => {
|
|
124
|
+
const counts = new Map();
|
|
125
|
+
visit(tree, (node) => {
|
|
126
|
+
if (isJsxElement(node) && node.name) {
|
|
127
|
+
counts.set(node.name, (counts.get(node.name) ?? 0) + 1);
|
|
128
|
+
}
|
|
129
|
+
});
|
|
130
|
+
return counts;
|
|
131
|
+
};
|
|
132
|
+
/** The document's heading levels, in order. */
|
|
133
|
+
export const collectHeadingDepths = (tree) => {
|
|
134
|
+
const depths = [];
|
|
135
|
+
visit(tree, 'heading', (node) => {
|
|
136
|
+
depths.push(node.depth);
|
|
137
|
+
});
|
|
138
|
+
return depths;
|
|
139
|
+
};
|
|
140
|
+
/**
|
|
141
|
+
* Every JSX attribute that carries a literal string value, keyed
|
|
142
|
+
* `Component.attribute`. Expression values are read through to their source
|
|
143
|
+
* text, which is what has to stay byte-identical.
|
|
144
|
+
*/
|
|
145
|
+
export const collectJsxAttributes = (tree) => {
|
|
146
|
+
const values = new Map();
|
|
147
|
+
visit(tree, (node) => {
|
|
148
|
+
if (!isJsxElement(node) || !node.name) {
|
|
149
|
+
return;
|
|
150
|
+
}
|
|
151
|
+
for (const attr of node.attributes) {
|
|
152
|
+
if (attr.type === 'mdxJsxExpressionAttribute') {
|
|
153
|
+
push(values, `${node.name}.{...}`, attr.value);
|
|
154
|
+
continue;
|
|
155
|
+
}
|
|
156
|
+
if (attr.value == null) {
|
|
157
|
+
continue;
|
|
158
|
+
}
|
|
159
|
+
push(values, `${node.name}.${attr.name}`, typeof attr.value === 'string' ? attr.value : attr.value.value);
|
|
160
|
+
}
|
|
161
|
+
});
|
|
162
|
+
return values;
|
|
163
|
+
};
|
|
164
|
+
const push = (map, key, value) => {
|
|
165
|
+
const list = map.get(key);
|
|
166
|
+
if (list) {
|
|
167
|
+
list.push(value);
|
|
168
|
+
}
|
|
169
|
+
else {
|
|
170
|
+
map.set(key, [value]);
|
|
171
|
+
}
|
|
172
|
+
};
|
|
173
|
+
const EXTERNAL_URL = /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i;
|
|
174
|
+
const LOCALE_PREFIX = new RegExp(`^/(?:${SUPPORTED_LANGUAGES.join('|')})(?=/|$)`);
|
|
175
|
+
/**
|
|
176
|
+
* Resolves a link the way the site does — against the position of the document
|
|
177
|
+
* that holds it — and then drops the language segment.
|
|
178
|
+
*
|
|
179
|
+
* This is what makes source and translation comparable at all. A translation's
|
|
180
|
+
* links legitimately differ from the source's as *written*: assets are rewritten
|
|
181
|
+
* to point back into the source-language tree (`../../../en/…/x.png`) because
|
|
182
|
+
* they are not copied per language. Resolved and de-localised, both spellings
|
|
183
|
+
* name the same file, so anything still different is a real difference.
|
|
184
|
+
*/
|
|
185
|
+
export const resolveLinkTarget = (url, docDirInRoot) => {
|
|
186
|
+
const trimmed = url.trim();
|
|
187
|
+
if (!trimmed || EXTERNAL_URL.test(trimmed) || trimmed.startsWith('#')) {
|
|
188
|
+
return trimmed;
|
|
189
|
+
}
|
|
190
|
+
const hashAt = trimmed.indexOf('#');
|
|
191
|
+
const target = hashAt < 0 ? trimmed : trimmed.slice(0, hashAt);
|
|
192
|
+
const hash = hashAt < 0 ? '' : trimmed.slice(hashAt);
|
|
193
|
+
if (!target) {
|
|
194
|
+
return trimmed;
|
|
195
|
+
}
|
|
196
|
+
const absolute = target.startsWith('/')
|
|
197
|
+
? path.posix.normalize(target)
|
|
198
|
+
: path.posix.resolve(`/${docDirInRoot}`, target);
|
|
199
|
+
return absolute.replace(LOCALE_PREFIX, '') + hash;
|
|
200
|
+
};
|
|
201
|
+
const LINK_ATTRIBUTES = new Set(['href', 'src']);
|
|
202
|
+
const HTML_LINK_ATTRIBUTE = /\b(?:href|src)\s*=\s*(["'])(.*?)\1/gi;
|
|
203
|
+
/**
|
|
204
|
+
* Every link target a document points at: markdown links and images, reference
|
|
205
|
+
* definitions, `href`/`src` on components, and the same inside raw HTML.
|
|
206
|
+
*/
|
|
207
|
+
export const collectLinkTargets = (tree, docDirInRoot) => {
|
|
208
|
+
const targets = [];
|
|
209
|
+
const add = (url) => {
|
|
210
|
+
const resolved = resolveLinkTarget(url, docDirInRoot);
|
|
211
|
+
if (resolved) {
|
|
212
|
+
targets.push(resolved);
|
|
213
|
+
}
|
|
214
|
+
};
|
|
215
|
+
visit(tree, (node) => {
|
|
216
|
+
switch (node.type) {
|
|
217
|
+
case 'link':
|
|
218
|
+
case 'image':
|
|
219
|
+
case 'definition': {
|
|
220
|
+
add(node.url);
|
|
221
|
+
return;
|
|
222
|
+
}
|
|
223
|
+
case 'html': {
|
|
224
|
+
for (const [, , value] of node.value.matchAll(HTML_LINK_ATTRIBUTE)) {
|
|
225
|
+
add(value);
|
|
226
|
+
}
|
|
227
|
+
return;
|
|
228
|
+
}
|
|
229
|
+
default: {
|
|
230
|
+
if (!isJsxElement(node)) {
|
|
231
|
+
return;
|
|
232
|
+
}
|
|
233
|
+
for (const attr of node.attributes) {
|
|
234
|
+
if (attr.type === 'mdxJsxAttribute' &&
|
|
235
|
+
LINK_ATTRIBUTES.has(attr.name) &&
|
|
236
|
+
typeof attr.value === 'string') {
|
|
237
|
+
add(attr.value);
|
|
238
|
+
}
|
|
239
|
+
}
|
|
240
|
+
}
|
|
241
|
+
}
|
|
242
|
+
});
|
|
243
|
+
return targets;
|
|
244
|
+
};
|
|
245
|
+
/** Multiset difference, reported as what is missing and what is extra. */
|
|
246
|
+
export const diffMultiset = (expected, actual) => {
|
|
247
|
+
const counts = new Map();
|
|
248
|
+
for (const value of expected) {
|
|
249
|
+
counts.set(value, (counts.get(value) ?? 0) + 1);
|
|
250
|
+
}
|
|
251
|
+
for (const value of actual) {
|
|
252
|
+
counts.set(value, (counts.get(value) ?? 0) - 1);
|
|
253
|
+
}
|
|
254
|
+
const missing = [];
|
|
255
|
+
const extra = [];
|
|
256
|
+
for (const [value, delta] of counts) {
|
|
257
|
+
for (let i = 0; i < delta; i++) {
|
|
258
|
+
missing.push(value);
|
|
259
|
+
}
|
|
260
|
+
for (let i = 0; i < -delta; i++) {
|
|
261
|
+
extra.push(value);
|
|
262
|
+
}
|
|
263
|
+
}
|
|
264
|
+
return { missing: missing.sort(), extra: extra.sort() };
|
|
265
|
+
};
|
|
266
|
+
/**
|
|
267
|
+
* The document's prose — the text a reader reads, and the only text a
|
|
268
|
+
* translation is supposed to change.
|
|
269
|
+
*
|
|
270
|
+
* Code, inline code and component attributes are excluded because they are not
|
|
271
|
+
* prose: counting them would make a page full of `kubectl` commands look
|
|
272
|
+
* untranslated, and would make a translated page look longer or shorter than it
|
|
273
|
+
* is for reasons that have nothing to do with the translation.
|
|
274
|
+
*/
|
|
275
|
+
export const collectProseText = (tree) => {
|
|
276
|
+
const parts = [];
|
|
277
|
+
visit(tree, 'text', (node) => {
|
|
278
|
+
parts.push(node.value);
|
|
279
|
+
});
|
|
280
|
+
return parts.join(' ');
|
|
281
|
+
};
|
|
282
|
+
/** The directory a document sits in, relative to the docs root, in posix form. */
|
|
283
|
+
export const docDirInRoot = (targetLang, relativePath) => {
|
|
284
|
+
const dir = path.posix.dirname(`${targetLang}/${relativePath}`);
|
|
285
|
+
return dir === '.' ? '' : dir;
|
|
286
|
+
};
|
|
@@ -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
|
+
});
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
import { lintRule } from 'unified-lint-rule';
|
|
2
|
+
import { SKIP, visit } from 'unist-util-visit';
|
|
3
|
+
import { currentPair, diffMultiset } from "./shared.js";
|
|
4
|
+
/**
|
|
5
|
+
* URLs written in prose that markdown does not turn into links still survive
|
|
6
|
+
* translation.
|
|
7
|
+
*
|
|
8
|
+
* This is the other half of a deliberate asymmetry. A URL with a scheme becomes
|
|
9
|
+
* a link node and is protected structurally; a bare `example.com` or an
|
|
10
|
+
* `ftp://…` stays plain text, and protecting *that* would mean pattern-matching
|
|
11
|
+
* inside prose — the one way masking could swallow something that ought to have
|
|
12
|
+
* been translated. So it is checked instead: a check that misfires costs one
|
|
13
|
+
* finding to read, whereas a mask that misfires hides a sentence.
|
|
14
|
+
*
|
|
15
|
+
* The pattern insists on a scheme or a `www.`, which is narrower than "looks
|
|
16
|
+
* like a domain" on purpose. A first attempt matched any `name.tld/path` and
|
|
17
|
+
* reported seven documents — every one an API group or an annotation key
|
|
18
|
+
* (`autoscaling.k8s.io/v1`, `kubevirt.io/storage`) that had merely moved
|
|
19
|
+
* between prose and inline code. Those are identifiers, not links, and a guard
|
|
20
|
+
* that cries wolf about them is worse than no guard at all.
|
|
21
|
+
*
|
|
22
|
+
* Honest caveat: measured exposure on this corpus is zero — all seven bare URLs
|
|
23
|
+
* carry `https://`, which makes them link nodes, protected structurally. This
|
|
24
|
+
* is a guard for a case nothing else covers, not a demonstrated detector.
|
|
25
|
+
*/
|
|
26
|
+
const BARE_URL = /\b(?:[a-z][a-z0-9+.-]*:\/\/|www\.)\S+/gi;
|
|
27
|
+
/**
|
|
28
|
+
* Text inside a link is not prose for this purpose.
|
|
29
|
+
*
|
|
30
|
+
* The rule's whole premise is that a URL markdown *did* turn into a link is
|
|
31
|
+
* protected structurally and belongs to `link-isomorphism`. The first
|
|
32
|
+
* implementation still walked into link nodes, so an autolink counted twice:
|
|
33
|
+
* once as a target and once as the label text that repeats it. That is not
|
|
34
|
+
* merely redundant. A translator that writes `[http://host:8080](http://host:8080)`
|
|
35
|
+
* — the one spelling of a bare URL that Chinese sentence punctuation cannot
|
|
36
|
+
* corrupt — had its label read as prose, found the URL missing from it (the
|
|
37
|
+
* port is a `textDirective` there), and was told it had lost a URL it had in
|
|
38
|
+
* fact preserved exactly. No spelling it could reach satisfied both rules, so
|
|
39
|
+
* the repair loop could only run out of rounds.
|
|
40
|
+
*/
|
|
41
|
+
const IS_LINK = new Set(['link', 'linkReference', 'definition']);
|
|
42
|
+
export const collectProseUrls = (tree) => {
|
|
43
|
+
const found = [];
|
|
44
|
+
visit(tree, (node) => {
|
|
45
|
+
if (IS_LINK.has(node.type)) {
|
|
46
|
+
return SKIP;
|
|
47
|
+
}
|
|
48
|
+
if (node.type !== 'text') {
|
|
49
|
+
return;
|
|
50
|
+
}
|
|
51
|
+
for (const [match] of node.value.matchAll(BARE_URL)) {
|
|
52
|
+
found.push(match);
|
|
53
|
+
}
|
|
54
|
+
});
|
|
55
|
+
return found;
|
|
56
|
+
};
|
|
57
|
+
export const translationUrlResidue = lintRule('doom-lint:translation-url-residue', async (tree, vfile) => {
|
|
58
|
+
const pair = await currentPair(tree, vfile);
|
|
59
|
+
if (!pair) {
|
|
60
|
+
return;
|
|
61
|
+
}
|
|
62
|
+
const { missing } = diffMultiset(collectProseUrls(pair.sourceTree), collectProseUrls(tree));
|
|
63
|
+
if (!missing.length) {
|
|
64
|
+
return;
|
|
65
|
+
}
|
|
66
|
+
vfile.message(`Translation lost ${missing.length} URL(s) written in prose: ${missing.map((url) => `\`${url}\``).join(', ')}. These are plain text rather than links, so nothing protects them structurally.`, tree);
|
|
67
|
+
});
|
package/lib/remarkrc.d.ts
CHANGED