From 2f9a1e758e3f033830a84ed224f39c84798d3d8c Mon Sep 17 00:00:00 2001 From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com> Date: Sat, 14 Nov 2026 20:45:42 +0000 Subject: [PATCH 1/5] fix(i18n): separate ambiguous translation calls throughout frontend Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com> --- .../RightSidebar/EnvelopeFilesList.vue | 10 ++++- .../validation/EnvelopeValidation.vue | 13 +++++- src/components/validation/SignerDetails.vue | 40 +++++++++++++++++-- src/views/CrlManagement/CrlManagement.vue | 10 ++++- src/views/FilesList/FilesList.vue | 3 +- .../PolicyWorkbench/Catalog/Catalog.vue | 20 +++++++++- src/views/Validation.vue | 13 +++++- 7 files changed, 96 insertions(+), 13 deletions(-) diff --git a/src/components/RightSidebar/EnvelopeFilesList.vue b/src/components/RightSidebar/EnvelopeFilesList.vue index cc133631e8..9e003ddaec 100644 --- a/src/components/RightSidebar/EnvelopeFilesList.vue +++ b/src/components/RightSidebar/EnvelopeFilesList.vue @@ -49,7 +49,7 @@
- {{ selectedCount > 0 ? t('libresign', '{count} selected', { count: selectedCount }) : t('libresign', 'Select all') }} + {{ selectionLabel }} [ }, ]) const selectedCount = computed(() => selectedFiles.value.length) +const selectionLabel = computed(() => { + if (selectedCount.value > 0) { + // TRANSLATORS {count} is the number of selected PDF files in an envelope. + return t('libresign', '{count} selected', { count: selectedCount.value }) + } + // TRANSLATORS Action to select all PDF files in an envelope. + return t('libresign', 'Select all') +}) const allSelected = computed(() => files.value.length > 0 && selectedFiles.value.length === files.value.length) watch(() => props.open, (newVal) => { diff --git a/src/components/validation/EnvelopeValidation.vue b/src/components/validation/EnvelopeValidation.vue index 3a136bc720..f09001ced3 100644 --- a/src/components/validation/EnvelopeValidation.vue +++ b/src/components/validation/EnvelopeValidation.vue @@ -79,7 +79,7 @@ - + - + {{ t('libresign', 'Validation') }} From f2e245e9ac56604e43e7ccde6c5ce805bbf3cd39 Mon Sep 17 00:00:00 2001 From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com> Date: Sat, 14 Nov 2026 20:56:39 +0000 Subject: [PATCH 4/5] ci(i18n): reject colon-prefixed and repeated translator hints Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com> --- AGENTS.md | 5 +- CONTRIBUTING.md | 9 +-- scripts/check-translator-hints.mjs | 42 ++++++++++++- scripts/tests/check-translator-hints.test.mjs | 62 ++++++++++++++++--- 4 files changed, 101 insertions(+), 17 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 23dad82887..70c810a204 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -111,8 +111,9 @@ runtime files. Prefer focused commands while diagnosing a small change. Follow [CONTRIBUTING.md](CONTRIBUTING.md#translation-strings-and-translator-context) and Nextcloud's translation guide. Keep one `t()`/`n()` per source line and -attach each `TRANSLATORS` hint to its specific string; `TRANSLATORS:` is -also supported. The `npm run lint` check blocks ambiguous same-line calls. +attach one `TRANSLATORS` hint to each specific string, without a colon +after the marker. Do not repeat consecutive hints. The `npm run lint` check +blocks ambiguous same-line calls, colon-prefixed hints and repeated hints. ## Command discovery and testing map diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 47fc87f8bc..f22993fa66 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -74,12 +74,13 @@ and [writing guide](https://docs.nextcloud.com/server/stable/developer_manual/de - Keep each complete user-facing message inside its own `t()` or `n()` call. Do not concatenate translated fragments or put two translation calls on the same physical source line. When choosing between messages, use separate branches, - each with its own translation call and context hint. + each with its own translation call and context hint. Do not repeat a hint + multiple times immediately before one translation call. - Add a factual `TRANSLATORS` hint for ambiguous terms, placeholders, and workflow-specific actions. Place it directly before the corresponding call: - `// TRANSLATORS ...` in scripts, or `` before the - translated element in Vue templates. Nextcloud accepts both - `TRANSLATORS` and `TRANSLATORS:`; the colon is not the issue. + `// TRANSLATORS ...` in scripts, or `` before the + translated element in Vue templates. Although Nextcloud accepts an optional + colon, LibreSign consistently omits the colon after `TRANSLATORS`. - Put hints on the actual `t()` calls, not on template references such as `{{ actionLabel }}`, whose translations are defined elsewhere. - Do not edit generated translations under `l10n/`; they are synchronized. diff --git a/scripts/check-translator-hints.mjs b/scripts/check-translator-hints.mjs index cb5e904295..90f84c3c5d 100644 --- a/scripts/check-translator-hints.mjs +++ b/scripts/check-translator-hints.mjs @@ -34,15 +34,51 @@ export function findAmbiguousTranslatorLines(source) { return badLines } +const translatorHint = /^\s*(?:\/\/|#|', + "{{ t('libresign', 'Review') }}", ].join('\n') - assert.deepEqual(findAmbiguousTranslatorLines(source), []) + assert.deepEqual(findTranslatorHintProblems(valid), []) + + const colon = ':' + const invalid = [ + '// TRANSLATORS' + colon + ' Label to confirm a saved document.', + "const save = t('libresign', 'Save')", + '', + "{{ t('libresign', 'Review') }}", + ].join('\n') + assert.deepEqual(findTranslatorHintProblems(invalid), [ + { line: 1, message: 'Use TRANSLATORS without a colon.' }, + { line: 3, message: 'Use TRANSLATORS without a colon.' }, + ]) +}) + +test('blocks triplicated translator hints above one translation', () => { + const source = [ + '', + '', + '', + "{{ t('libresign', 'Approved') }}", + ].join('\n') + assert.deepEqual(findTranslatorHintProblems(source), [ + { line: 2, message: 'Use only one TRANSLATORS hint for a translation.' }, + { line: 3, message: 'Use only one TRANSLATORS hint for a translation.' }, + ]) +}) + +test('blocks two consecutive hints even if their text differs', () => { + const source = [ + '// TRANSLATORS Describes a document state.', + '// TRANSLATORS Describes an approval state.', + "return t('libresign', 'Pending')", + ].join('\n') + assert.deepEqual(findTranslatorHintProblems(source), [ + { line: 2, message: 'Use only one TRANSLATORS hint for a translation.' }, + ]) +}) + +test('permits repeated context only for distinct translation calls', () => { + const source = [ + '// TRANSLATORS Label on the approval button.', + "return t('libresign', 'Approve')", + '// TRANSLATORS Label on the approval button.', + "return t('libresign', 'Approve')", + ].join('\n') + assert.deepEqual(findTranslatorHintProblems(source), []) }) test('blocks a one-line conditional with two translation calls', () => { @@ -44,7 +90,7 @@ test('blocks nested translations on a single source line', () => { test('does not count commented-out examples as runtime translations', () => { const source = [ "// return [t('libresign', 'Save'), t('libresign', 'Cancel')]", - '', + '', "{{ t('libresign', 'Ready') }}", ].join('\n') assert.deepEqual(findAmbiguousTranslatorLines(source), []) From 084a7580255a43ffbe4ee6324e085ba46c980e6d Mon Sep 17 00:00:00 2001 From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com> Date: Sat, 14 Nov 2026 20:56:49 +0000 Subject: [PATCH 5/5] docs(i18n): link canonical translation guide instead of duplicating it Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com> --- AGENTS.md | 8 +++----- CONTRIBUTING.md | 44 ++++---------------------------------------- 2 files changed, 7 insertions(+), 45 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 70c810a204..381a1db225 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -109,11 +109,9 @@ runtime files. Prefer focused commands while diagnosing a small change. ## Translator context hints -Follow [CONTRIBUTING.md](CONTRIBUTING.md#translation-strings-and-translator-context) -and Nextcloud's translation guide. Keep one `t()`/`n()` per source line and -attach one `TRANSLATORS` hint to each specific string, without a colon -after the marker. Do not repeat consecutive hints. The `npm run lint` check -blocks ambiguous same-line calls, colon-prefixed hints and repeated hints. +Follow the [LibreSign translation guide](https://docs.libresign.coop/developer_manual/translation.html) +for the code conventions and the maintained contributor examples. +The `npm run lint:translator-hints` check enforces the source structure. ## Command discovery and testing map diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f22993fa66..f6c6e77df9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -66,46 +66,10 @@ AI-assisted contributions are welcome. You may use AI for any part of the contri When updating your branch with changes from `main`, rebasing is preferred when practical because it avoids unnecessary merge commits and keeps the pull request history easier to review. -### Translation strings and translator context - -LibreSign follows the [Nextcloud developer translation guide](https://docs.nextcloud.com/server/stable/developer_manual/basics/front-end/l10n.html) -and [writing guide](https://docs.nextcloud.com/server/stable/developer_manual/design/writing.html). - -- Keep each complete user-facing message inside its own `t()` or `n()` call. - Do not concatenate translated fragments or put two translation calls on the same - physical source line. When choosing between messages, use separate branches, - each with its own translation call and context hint. Do not repeat a hint - multiple times immediately before one translation call. -- Add a factual `TRANSLATORS` hint for ambiguous terms, placeholders, and - workflow-specific actions. Place it directly before the corresponding call: - `// TRANSLATORS ...` in scripts, or `` before the - translated element in Vue templates. Although Nextcloud accepts an optional - colon, LibreSign consistently omits the colon after `TRANSLATORS`. -- Put hints on the actual `t()` calls, not on template references such as - `{{ actionLabel }}`, whose translations are defined elsewhere. -- Do not edit generated translations under `l10n/`; they are synchronized. - -**Good (one hint per message):** - -```ts -if (isApprover) { - // TRANSLATORS Action for a reviewer who approves a submitted document through their signature. - return t('libresign', 'Sign and approve document') -} -// TRANSLATORS Action for an ordinary signer of a document. -return t('libresign', 'Sign document') -``` - -**Bad (second string loses its own translator context):** - -```ts -// TRANSLATORS Ambiguous: one comment cannot explain both alternatives. -return isApprover ? t('libresign', 'Approve') : t('libresign', 'Sign') -``` - -The `npm run lint` CI job invokes `npm run lint:translator-hints` and blocks -multiple translation calls on the same source line. The Node test suite for -this check is `npm run test:translator-hints`. +### Translation + +For contributing translations and writing translator context hints in code, +see the [LibreSign translation guide](https://docs.libresign.coop/developer_manual/translation.html). ### Front and backend development environment