From 61b353ebeeed9f199e2fe27c62258795113dcc00 Mon Sep 17 00:00:00 2001 From: Kam Date: Sun, 6 Sep 2026 02:07:10 +0300 Subject: [PATCH] fix(docs-infra): restore the xlf regions on the i18n guides #65848 renamed `messages.fr.xlf.html` to `messages.fr.xlf` and, in the same lines, reverted `region=` back to `visibleRegion=`, undoing #65530 from two weeks earlier. `visibleRegion` is not read by the tokenizer, and `xlf` is not in `REGION_MATCHERS`, so both halves of the snippet handling broke at once. Since then https://angular.dev/guide/i18n/translation-files has shown the same 78 line file ten times where the prose describes single `` elements, and https://angular.dev/guide/i18n/manage-marked-text three times, each carrying the `#docregion` scaffolding into the rendered code. Mapping `xlf` to the html matcher also cleans up https://angular.dev/guide/i18n/example, which renders the whole file on purpose but leaked 27 marker lines into it. `docs-code.spec.mts` already loads this fixture but only asserted the block existed, so it stayed green throughout. It now also asserts no marker survives. --- .../marked/test/docs-code/docs-code.spec.mts | 1 + .../pipeline/shared/regions/region-parser.mts | 1 + .../shared/regions/remove-eslint-comments.mts | 1 + .../content/guide/i18n/manage-marked-text.md | 6 +++--- .../content/guide/i18n/translation-files.md | 20 +++++++++---------- 5 files changed, 16 insertions(+), 13 deletions(-) diff --git a/adev/shared-docs/pipeline/shared/marked/test/docs-code/docs-code.spec.mts b/adev/shared-docs/pipeline/shared/marked/test/docs-code/docs-code.spec.mts index 270647d5258..33022e377b9 100644 --- a/adev/shared-docs/pipeline/shared/marked/test/docs-code/docs-code.spec.mts +++ b/adev/shared-docs/pipeline/shared/marked/test/docs-code/docs-code.spec.mts @@ -46,6 +46,7 @@ describe('markdown to html', () => { it('should load header and html code', () => { const codeBlock = markdownDocument.querySelectorAll('code')[3]; expect(codeBlock).toBeTruthy(); + expect(codeBlock?.textContent).not.toContain('docregion'); }); it('should not link property names in object literals', () => { diff --git a/adev/shared-docs/pipeline/shared/regions/region-parser.mts b/adev/shared-docs/pipeline/shared/regions/region-parser.mts index 4047c86f7d0..bb0b025bebe 100644 --- a/adev/shared-docs/pipeline/shared/regions/region-parser.mts +++ b/adev/shared-docs/pipeline/shared/regions/region-parser.mts @@ -27,6 +27,7 @@ const REGION_MATCHERS = { es6: inlineC, html: html, svg: html, + xlf: html, css: blockC, conf: inlineHash, yaml: inlineHash, diff --git a/adev/shared-docs/pipeline/shared/regions/remove-eslint-comments.mts b/adev/shared-docs/pipeline/shared/regions/remove-eslint-comments.mts index 701a4871311..e22c4a9a0c2 100644 --- a/adev/shared-docs/pipeline/shared/regions/remove-eslint-comments.mts +++ b/adev/shared-docs/pipeline/shared/regions/remove-eslint-comments.mts @@ -13,6 +13,7 @@ export type FileType = | 'es6' | 'html' | 'svg' + | 'xlf' | 'css' | 'conf' | 'yaml' diff --git a/adev/src/content/guide/i18n/manage-marked-text.md b/adev/src/content/guide/i18n/manage-marked-text.md index e2de6098c0f..453f583a331 100644 --- a/adev/src/content/guide/i18n/manage-marked-text.md +++ b/adev/src/content/guide/i18n/manage-marked-text.md @@ -9,7 +9,7 @@ As described in [How meanings control text extraction and merges][GuideI18nCommo The following example displays translation units with unique IDs. - + When you change the translatable text, the extractor generates a new ID for that translation unit. In most cases, changes in the source text also require a change to the translation. @@ -34,7 +34,7 @@ variableText1 = $localize`:@@introductionHeader:Hello i18n!`; When you specify a custom ID, the extractor generates a translation unit with the custom ID. - + If you change the text, the extractor does not change the ID. As a result, you don't have to take the extra step to update the translation. @@ -75,7 +75,7 @@ For example, in the following code snippet the same `myId` custom ID is defined The following displays the translation in French. - + Both elements now use the same translation \(`Bonjour`\), because both were defined with the same custom ID. diff --git a/adev/src/content/guide/i18n/translation-files.md b/adev/src/content/guide/i18n/translation-files.md index e684539b085..d082942d778 100644 --- a/adev/src/content/guide/i18n/translation-files.md +++ b/adev/src/content/guide/i18n/translation-files.md @@ -132,20 +132,20 @@ The following actions describe the translation process for French. 1. Open `messages.fr.xlf` and find the first `` element. This is a _translation unit_, also known as a _text node_, that represents the translation of the `

` greeting tag that was previously marked with the `i18n` attribute. - + The `id="introductionHeader"` is a [custom ID][GuideI18nOptionalManageMarkedText], but without the `@@` prefix required in the source HTML. 1. Duplicate the `... ` element in the text node, rename it to `target`, and then replace the content with the French text. - + In a more complex translation, the information and context in the [description and meaning elements][GuideI18nCommonPrepareAddHelpfulDescriptionsAndMeanings] help you choose the right words for translation. 1. Translate the other text nodes. The following example displays the way to translate. - + IMPORTANT: Don't change the IDs for translation units. Each `id` attribute is generated by Angular and depends on the content of the component text and the assigned meaning. @@ -169,7 +169,7 @@ To translate a `plural`, translate the ICU format match values. The following example displays the way to translate. - + ## Translate alternate expressions @@ -184,18 +184,18 @@ The following example displays a `select` ICU expression in the component templa In this example, Angular extracts the expression into two translation units. The first contains the text outside of the `select` clause, and uses a placeholder for `select` \(``\): - + IMPORTANT: When you translate the text, move the placeholder if necessary, but don't remove it. If you remove the placeholder, the ICU expression is removed from your translated application. The following example displays the second translation unit that contains the `select` clause. - + The following example displays both translation units after translation is complete. - + ## Translate nested expressions @@ -206,15 +206,15 @@ Angular extracts the expression into two translation units. The following example displays the first translation unit that contains the text outside of the nested expression. - + The following example displays the second translation unit that contains the complete nested expression. - + The following example displays both translation units after translating. - + ## What's next