diff --git a/AGENTS.md b/AGENTS.md
index b7eee94bfe..381a1db225 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -107,6 +107,12 @@ the application/web-server user for intentional Nextcloud runtime writes.
Some tests can alter Nextcloud state, generated certificates, app data or
runtime files. Prefer focused commands while diagnosing a small change.
+## Translator context 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
Use `make help` to discover the project's high-level development tasks. The
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b2907c4c0b..f6c6e77df9 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -66,6 +66,11 @@ 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
+
+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
More information [here](https://docs.libresign.coop/developer_manual/getting-started/development-environment/setup), at the [official documentation](https://docs.libresign.coop/developer_manual/getting-started/development-environment/setup)
diff --git a/lib/Handler/DocMdpHandler.php b/lib/Handler/DocMdpHandler.php
index 8f6c254be9..2c72fb217a 100644
--- a/lib/Handler/DocMdpHandler.php
+++ b/lib/Handler/DocMdpHandler.php
@@ -55,7 +55,7 @@ public function extractDocMdpData($resource): array {
if ($docmdpLevel->isCertifying() && $this->isOnlySingleDocMdpViolation($isoStatus)) {
$result['docmdp_validation'] = [
'valid' => false,
- // TRANSLATORS: Validation message shown for a PDF with more than one DocMDP (document modification policy) certifying signature. Only the first certifying signature defines the document permission level.
+ // TRANSLATORS Validation message shown for a PDF with more than one DocMDP (document modification policy) certifying signature. Only the first certifying signature defines the document permission level.
'message' => $this->l10n->t('Multiple DocMDP signatures detected. The first certifying signature determines the document\'s permission level.'),
];
}
@@ -284,7 +284,7 @@ private function detectModifications($pdfResource): array {
*/
private function validateModifications(DocMdpLevel $docmdpLevel, array $modificationInfo, $pdfResource): array {
if (!$modificationInfo['modified']) {
- // TRANSLATORS: Validation result for a signed PDF that was not changed after the signature was applied.
+ // TRANSLATORS Validation result for a signed PDF that was not changed after the signature was applied.
return $this->buildValidationResult(
true,
File::MODIFICATION_UNMODIFIED,
@@ -293,7 +293,7 @@ private function validateModifications(DocMdpLevel $docmdpLevel, array $modifica
}
if ($docmdpLevel === DocMdpLevel::NOT_CERTIFIED) {
- // TRANSLATORS: Validation result for a signed PDF that was modified, but the document has no DocMDP certification restrictions.
+ // TRANSLATORS Validation result for a signed PDF that was modified, but the document has no DocMDP certification restrictions.
return $this->buildValidationResult(
true,
File::MODIFICATION_ALLOWED,
@@ -305,7 +305,7 @@ private function validateModifications(DocMdpLevel $docmdpLevel, array $modifica
$allowedTypes = self::ALLOWED_MODIFICATIONS[$docmdpLevel->name] ?? null;
if ($allowedTypes === null) {
- // TRANSLATORS: Validation error for a signed PDF modified in a way that violates its DocMDP (document modification policy) certification rules.
+ // TRANSLATORS Validation error for a signed PDF modified in a way that violates its DocMDP (document modification policy) certification rules.
return $this->buildValidationResult(
false,
File::MODIFICATION_VIOLATION,
@@ -352,13 +352,13 @@ private function buildValidationResult(bool $valid, int $status, string $message
*/
private function getAllowedModificationMessage(DocMdpLevel $level): string {
return match ($level) {
- // TRANSLATORS: Validation error for a certified PDF with DocMDP level P=1, which does not allow any change after signing.
+ // TRANSLATORS Validation error for a certified PDF with DocMDP level P=1, which does not allow any change after signing.
DocMdpLevel::CERTIFIED_NO_CHANGES_ALLOWED => $this->l10n->t('Invalid: Document was modified after signing (DocMDP violation - no changes allowed)'),
- // TRANSLATORS: Validation result for a certified PDF with DocMDP level P=2. Only form field completion is allowed after signing.
+ // TRANSLATORS Validation result for a certified PDF with DocMDP level P=2. Only form field completion is allowed after signing.
DocMdpLevel::CERTIFIED_FORM_FILLING => $this->l10n->t('Document form fields were modified (allowed by DocMDP P=2)'),
- // TRANSLATORS: Validation result for a certified PDF with DocMDP level P=3. Form field completion and annotations are allowed after signing.
+ // TRANSLATORS Validation result for a certified PDF with DocMDP level P=3. Form field completion and annotations are allowed after signing.
DocMdpLevel::CERTIFIED_FORM_FILLING_AND_ANNOTATIONS => $this->l10n->t('Document form fields or annotations were modified (allowed by DocMDP P=3)'),
- // TRANSLATORS: Generic validation result for a signed PDF that was modified after signing.
+ // TRANSLATORS Generic validation result for a signed PDF that was modified after signing.
default => $this->l10n->t('Document was modified after signing'),
};
}
@@ -371,13 +371,13 @@ private function getAllowedModificationMessage(DocMdpLevel $level): string {
*/
private function getViolationMessage(DocMdpLevel $level): string {
return match ($level) {
- // TRANSLATORS: Validation error for a certified PDF with DocMDP level P=1, which does not allow any change after signing.
+ // TRANSLATORS Validation error for a certified PDF with DocMDP level P=1, which does not allow any change after signing.
DocMdpLevel::CERTIFIED_NO_CHANGES_ALLOWED => $this->l10n->t('Invalid: Document was modified after signing (DocMDP violation - no changes allowed)'),
- // TRANSLATORS: Validation error for a certified PDF with DocMDP level P=2. Only form field completion is allowed after signing.
+ // TRANSLATORS Validation error for a certified PDF with DocMDP level P=2. Only form field completion is allowed after signing.
DocMdpLevel::CERTIFIED_FORM_FILLING => $this->l10n->t('Invalid: Document was modified after signing (DocMDP P=2 only allows form field changes)'),
- // TRANSLATORS: Validation error for a certified PDF with DocMDP level P=3. Only form field completion and annotations are allowed after signing.
+ // TRANSLATORS Validation error for a certified PDF with DocMDP level P=3. Only form field completion and annotations are allowed after signing.
DocMdpLevel::CERTIFIED_FORM_FILLING_AND_ANNOTATIONS => $this->l10n->t('Invalid: Document was modified after signing (DocMDP P=3 only allows form fields and annotations)'),
- // TRANSLATORS: Generic validation error for a signed PDF modified in a way that violates DocMDP (document modification policy) certification rules.
+ // TRANSLATORS Generic validation error for a signed PDF modified in a way that violates DocMDP (document modification policy) certification rules.
default => $this->l10n->t('Invalid: Document was modified after signing (DocMDP violation)'),
};
}
diff --git a/lib/Handler/SigningErrorHandler.php b/lib/Handler/SigningErrorHandler.php
index 4df91109c8..083ea27b20 100644
--- a/lib/Handler/SigningErrorHandler.php
+++ b/lib/Handler/SigningErrorHandler.php
@@ -75,11 +75,11 @@ private function isKnownError(string $message): bool {
private function translateKnownError(string $message): string {
return match ($message) {
- // TRANSLATORS: Error returned when the signing service rejects a request to a local/private host for security reasons.
+ // TRANSLATORS Error returned when the signing service rejects a request to a local/private host for security reasons.
'Host violates local access rules.' => $this->l10n->t('Host violates local access rules.'),
- // TRANSLATORS: Error shown when the password provided to unlock the signing certificate is incorrect.
+ // TRANSLATORS Error shown when the password provided to unlock the signing certificate is incorrect.
'Certificate Password Invalid.' => $this->l10n->t('Certificate Password Invalid.'),
- // TRANSLATORS: Error shown when no password was provided to unlock the signing certificate.
+ // TRANSLATORS Error shown when no password was provided to unlock the signing certificate.
'Certificate Password is Empty.' => $this->l10n->t('Certificate Password is Empty.'),
default => $message,
};
@@ -92,7 +92,7 @@ private function formatUnknownError(string $message, \Throwable $exception): arr
$this->logger->error($message, ['exception' => $exception]);
return [[
- // TRANSLATORS: Multi-line error shown when an unexpected server error happens during signing. %1$s is the client IP address, %2$s is the request ID, and %3$s is the technical error message. Keep the Markdown formatting and line breaks.
+ // TRANSLATORS Multi-line error shown when an unexpected server error happens during signing. %1$s is the client IP address, %2$s is the request ID, and %3$s is the technical error message. Keep the Markdown formatting and line breaks.
'message' => $this->l10n->t(
"The server was unable to complete your request.\n"
. "If this happens again, please send the technical details below to the server administrator.\n"
diff --git a/lib/Middleware/InjectionMiddleware.php b/lib/Middleware/InjectionMiddleware.php
index c3e249ef8e..606bfd5127 100644
--- a/lib/Middleware/InjectionMiddleware.php
+++ b/lib/Middleware/InjectionMiddleware.php
@@ -174,7 +174,7 @@ private function isValidationUrlPrivate(): bool {
private function throwPrivateValidationRedirect(?string $redirectUrl): void {
throw new LibresignException(json_encode([
'action' => JSActions::ACTION_REDIRECT,
- // TRANSLATORS: Error shown to anonymous users when a private validation URL requires authentication before continuing.
+ // TRANSLATORS Error shown to anonymous users when a private validation URL requires authentication before continuing.
'errors' => [$this->l10n->t('You are not logged in. Please log in.')],
'redirect' => $this->urlGenerator->linkToRoute('core.login.showLoginForm', [
'redirect_url' => $redirectUrl,
@@ -308,7 +308,7 @@ private function maintainSessionConsistencyWithUuid(?string $uuid): void {
private function getLoggedIn(): void {
$user = $this->userSession->getUser();
if (!$user instanceof IUser) {
- // TRANSLATORS: Error shown when an anonymous user tries to create a signature request, an action allowed only for authenticated users with permission.
+ // TRANSLATORS Error shown when an anonymous user tries to create a signature request, an action allowed only for authenticated users with permission.
throw new \Exception($this->l10n->t('You are not allowed to create signature requests'), Http::STATUS_UNPROCESSABLE_ENTITY);
}
$this->signingRequestValidator->canRequestSign($user);
diff --git a/lib/Service/File/MessagesLoader.php b/lib/Service/File/MessagesLoader.php
index 216a154f3c..b695ce167a 100644
--- a/lib/Service/File/MessagesLoader.php
+++ b/lib/Service/File/MessagesLoader.php
@@ -35,7 +35,7 @@ public function loadMessages(
if (isset($fileData->settings['canSign']) && $fileData->settings['canSign']) {
$messages[] = [
'type' => 'info',
- // TRANSLATORS: Informational message shown in the file details UI when the current user is one of the required signers and still needs to sign the document.
+ // TRANSLATORS Informational message shown in the file details UI when the current user is one of the required signers and still needs to sign the document.
'message' => $this->l10n->t('You need to sign this document')
];
}
@@ -50,7 +50,7 @@ public function loadMessages(
if (empty($fileData->signers)) {
$messages[] = [
'type' => 'info',
- // TRANSLATORS: Informational message shown when the current user can request signatures in general, but no eligible signer can be added for this specific document.
+ // TRANSLATORS Informational message shown when the current user can request signatures in general, but no eligible signer can be added for this specific document.
'message' => $this->l10n->t('You cannot create a signature request for this document. Please contact your administrator.')
];
}
diff --git a/lib/Service/IdentifyMethod/RuntimeRequirementValidator.php b/lib/Service/IdentifyMethod/RuntimeRequirementValidator.php
index 8350d8e79b..5c0227e9bc 100644
--- a/lib/Service/IdentifyMethod/RuntimeRequirementValidator.php
+++ b/lib/Service/IdentifyMethod/RuntimeRequirementValidator.php
@@ -117,7 +117,7 @@ private function summarizeVerificationState(array $methodsByName): array {
*/
public function validateRequiredFactorsCompleted(array $summary): void {
if ($summary['identifiedRequiredFactors'] < $summary['requiredFactors']) {
- // TRANSLATORS: Error shown when a signer tries to sign before completing every identification factor marked as required, such as email, password, or document validation.
+ // TRANSLATORS Error shown when a signer tries to sign before completing every identification factor marked as required, such as email, password, or document validation.
throw new LibresignException($this->l10n->t('You need to complete all required identification factors before signing.'));
}
}
@@ -131,7 +131,7 @@ public function validateRequiredFactorsCompleted(array $summary): void {
public function validateMinimumFactorsCompleted(array $summary, int $minimumTotalVerifiedFactors): void {
$requiredVerifiedFactors = max($summary['requiredFactors'], $minimumTotalVerifiedFactors);
if ($summary['identifiedFactors'] < $requiredVerifiedFactors) {
- // TRANSLATORS: Error shown when signing requires a minimum number of completed identification factors. %n is the required number of verified factors.
+ // TRANSLATORS Error shown when signing requires a minimum number of completed identification factors. %n is the required number of verified factors.
throw new LibresignException(
$this->l10n->n(
'You need to complete at least %n identification factor before signing.',
diff --git a/package.json b/package.json
index a471473106..f89b3fd0cd 100644
--- a/package.json
+++ b/package.json
@@ -7,8 +7,9 @@
"scripts": {
"build": "vite build",
"dev": "vite build --mode development",
- "lint": "eslint",
+ "lint": "eslint && npm run lint:translator-hints",
"lint:fix": "eslint --fix",
+ "lint:translator-hints": "node scripts/check-translator-hints.mjs",
"serve": "vite dev",
"stylelint": "stylelint src/**/*.scss src/**/*.vue",
"stylelint:fix": "stylelint src/**/*.scss src/**/*.vue --fix",
@@ -18,6 +19,7 @@
"test:e2e:report": "playwright show-report",
"test:e2e:ui": "playwright test --ui --ui-host=0.0.0.0 --ui-port=9323",
"test:mutation": "stryker run",
+ "test:translator-hints": "node --test scripts/tests/check-translator-hints.test.mjs",
"test:watch": "vitest",
"ts:check": "vue-tsc --noEmit",
"typescript:generate": "npx openapi-typescript -t",
diff --git a/scripts/check-translator-hints.mjs b/scripts/check-translator-hints.mjs
new file mode 100644
index 0000000000..90f84c3c5d
--- /dev/null
+++ b/scripts/check-translator-hints.mjs
@@ -0,0 +1,94 @@
+/**
+ * SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ *
+ * Nextcloud associates each translator hint with only the first translation
+ * call on the next line. Guard against multiple calls on a source line.
+ */
+import { execFileSync } from 'node:child_process'
+import process from 'node:process'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const translationCall = /(? 1) {
+ badLines.push(index + 1)
+ }
+ }
+ return badLines
+}
+
+const translatorHint = /^\s*(?:\/\/|#|',
+ "{{ t('libresign', 'Review') }}",
+ ].join('\n')
+ 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', () => {
+ const source = [
+ '// TRANSLATORS Only the first translation receives the hint on this source line.',
+ "const label = approved ? t('libresign', 'Approved') : t('libresign', 'Pending')",
+ ].join('\n')
+ assert.deepEqual(findAmbiguousTranslatorLines(source), [2])
+})
+
+test('blocks nested translations on a single source line', () => {
+ const source = [
+ "return t('libresign', 'Status: {status}', { status: t('libresign', 'Unknown') })",
+ ].join('\n')
+ assert.deepEqual(findAmbiguousTranslatorLines(source), [1])
+})
+
+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), [])
+})
diff --git a/src/components/LeftSidebar/LeftSidebar.vue b/src/components/LeftSidebar/LeftSidebar.vue
index c1fa28f173..f5d09da339 100644
--- a/src/components/LeftSidebar/LeftSidebar.vue
+++ b/src/components/LeftSidebar/LeftSidebar.vue
@@ -23,7 +23,7 @@
-
+