Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
5 changes: 5 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
24 changes: 12 additions & 12 deletions lib/Handler/DocMdpHandler.php
Original file line number Diff line number Diff line change
Expand Up @@ -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.'),
];
}
Expand Down Expand Up @@ -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,
Expand All @@ -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,
Expand All @@ -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,
Expand Down Expand Up @@ -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'),
};
}
Expand All @@ -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)'),
};
}
Expand Down
8 changes: 4 additions & 4 deletions lib/Handler/SigningErrorHandler.php
Original file line number Diff line number Diff line change
Expand Up @@ -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,
};
Expand All @@ -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"
Expand Down
4 changes: 2 additions & 2 deletions lib/Middleware/InjectionMiddleware.php
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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);
Expand Down
4 changes: 2 additions & 2 deletions lib/Service/File/MessagesLoader.php
Original file line number Diff line number Diff line change
Expand Up @@ -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')
];
}
Expand All @@ -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.')
];
}
Expand Down
4 changes: 2 additions & 2 deletions lib/Service/IdentifyMethod/RuntimeRequirementValidator.php
Original file line number Diff line number Diff line change
Expand Up @@ -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.'));
}
}
Expand All @@ -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.',
Expand Down
4 changes: 3 additions & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand All @@ -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",
Expand Down
94 changes: 94 additions & 0 deletions scripts/check-translator-hints.mjs
Original file line number Diff line number Diff line change
@@ -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 = /(?<![\w$])(?:t|n)\s*\(\s*(['"])libresign\1\s*,/g

/**
* @param {string} source
* @return {number[]}
*/
export function findAmbiguousTranslatorLines(source) {
const badLines = []
const lines = source.split(/\r?\n/)
for (let index = 0; index < lines.length; index++) {
const line = lines[index]
if (/^\s*(?:\/\/|\*|<!--)/.test(line)) {
continue
}
translationCall.lastIndex = 0
const count = [...line.matchAll(translationCall)].length
if (count > 1) {
badLines.push(index + 1)
}
}
return badLines
}

const translatorHint = /^\s*(?:\/\/|#|<!--|\/\*+|\*)\s*TRANSLATORS\b(.*)$/

/**
* Detect the LibreSign convention: colonless and one hint per translation.
*
* @param {string} source
* @return {{ line: number, message: string }[]}
*/
export function findTranslatorHintProblems(source) {
const problems = []
let previousWasHint = false
const lines = source.split(/\r?\n/)
for (let index = 0; index < lines.length; index++) {
const line = lines[index]
const hint = line.match(translatorHint)
if (!hint) {
if (line.trim()) {
previousWasHint = false
}
continue
}
if (/^\s*:/.test(hint[1])) {
problems.push({ line: index + 1, message: 'Use TRANSLATORS without a colon.' })
}
if (previousWasHint) {
problems.push({ line: index + 1, message: 'Use only one TRANSLATORS hint for a translation.' })
}
previousWasHint = true
}
return problems
}

export function checkTrackedSourceFiles() {
const files = execFileSync('git', ['ls-files', '-z', '--', 'src', 'lib', 'appinfo', 'tests', 'scripts'], { encoding: 'utf8' })
.split('\0')
.filter(path => /\.(?:vue|js|mjs|ts|php)$/.test(path) && !path.startsWith('src/types/openapi/') && !path.startsWith('scripts/tests/'))
const errors = []
for (const file of files) {
const content = readFileSync(file, 'utf8')
for (const line of findAmbiguousTranslatorLines(content)) {
errors.push(`${file}:${line}: multiple t()/n() calls on one line; split the calls and add separate TRANSLATORS hints.`)
}
for (const problem of findTranslatorHintProblems(content)) {
errors.push(`${file}:${problem.line}: ${problem.message}`)
}
}
return errors
}

if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
const errors = checkTrackedSourceFiles()
if (errors.length > 0) {
process.stderr.write(errors.join('\n') + '\n')
process.exitCode = 1
} else {
process.stdout.write('Translator-hint structure check passed.\n')
}
}
Loading
Loading