Skip to content

docs: add Brazilian Portuguese and Russian READMEs - #770

Open
2160039878-cyber wants to merge 1 commit into
libredb:mainfrom
2160039878-cyber:docs/localized-readmes-594-610
Open

docs: add Brazilian Portuguese and Russian READMEs#770
2160039878-cyber wants to merge 1 commit into
libredb:mainfrom
2160039878-cyber:docs/localized-readmes-594-610

Conversation

@2160039878-cyber

@2160039878-cyber 2160039878-cyber commented Sep 10, 2026

Copy link
Copy Markdown
Contributor

Description

Brazilian Portuguese and Russian readers currently have no localized entry point. Add two abridged READMEs covering the project, supported engines, installation, quick start, security, AI data flow, and contribution requirements. Both translations share the language-switcher and drift-guard update in this PR.

Type of Change

  • Documentation update
  • Test addition or update

Related Issue

Closes #594
Closes #610

Claims: Portuguese, Russian.

Changes Made

  • Add README_pt.md (251 lines) and README_ru.md (254 lines), following the existing abridged scope. Preserve the 16 canonical engine names and quote install-table commands verbatim.
  • Keep deb/rpm, AppImage, Snap, standalone tarball, and npx/npm visible, including the distinction between the server and desktop packages. Explain the agent's supported engines and what the configured model endpoint receives.
  • Update all six language switchers, including the Spanish README already on main, and register both new files in LOCALIZED.
  • Add four CLI regression cases: a missing engine and a changed install command in each new language must fail the guard. All four failed before registration and pass afterward.

Testing

  • Tested locally
  • Added regression tests
  • All existing tests pass

Local validation on a767100f700c10cf44a4de0aaca02b4c00b8f31c:

  • bun run test:unit --isolate --pass-with-no-tests -t 'parseTables|table lookup|extraction|checkReadmes|readme-check CLI': 45 passed, including all 31 drift-guard tests. The name filter also selected 14 existing tests.
  • bun run readme:check: both new translations match the canonical engine set and install commands.
  • bun run format, lint, typecheck, knip, chart:check, channels:showcase:check, security:check, and build: passed.
  • Verified all six switchers and all 64 relative file links in the new READMEs; reviewed both translations against the English README and the distribution/agent documentation.

The complete local bun run test / coverage run was not repeated: this Windows environment lacks the Helm/chart test prerequisites and has known unrelated SQLite file-lock limitations. Full-suite, coverage, E2E and engine checks are left to the required CI workflows. No installation command in the documentation was executed as part of translation validation.

Test Environment

  • Base: 2f4ae61216956824410ba2f16bae3f697348afe3
  • OS: Windows x64
  • Node.js: 24.18.1; Bun: 1.4.2
  • Browser / database: not applicable to this documentation change

Checklist

  • My code follows the project's code style guidelines
  • I have performed a self-review of my code
  • I have updated the documentation accordingly
  • I have added tests that prove my fix is effective or that my feature works
  • New and existing targeted unit tests pass locally with my changes
  • The required CI test job passes the 100% line-coverage gate (bun run test:coverage and bun run coverage:check)
  • Provider triad: not applicable; no provider files changed.
  • Dependencies: both issues are included together so the language-switcher links resolve within this PR.

Additional Notes

Prepared with Codex, including AI-assisted translation and test authoring. Technical claims, terminology, commands, and links were reviewed and revised against the source documents; no independent native-speaker review is claimed. Language-quality feedback is welcome. The drift guard verifies technical invariants, not linguistic quality.

@cevheri

cevheri commented Sep 10, 2026

Copy link
Copy Markdown
Member

This is done. Merging shortly.

The part I checked hardest was the guard, because scripts/readme-check.mjs runs inside a required check and a guard that quietly stops noticing is worse than no guard. Adding the two files to LOCALIZED is the whole change, which is right: one list, one registration point, and the success line now names all five so the output states its own coverage.

Verified both invariants on both new files rather than assuming the list entry was enough. Replacing the **PostgreSQL** row in README_pt.md gives no engine table found and exit 1, same in README_ru.md, and changing docker run to docker run --rm inside README_pt.md's install table gives does not appear verbatim in README.md. Your own unit cases are better than my file-level probes, though: running the CLI against synthetic README_pt/README_ru content and asserting exit 1 with the specific stderr is hermetic, where mine depended on the real files.

The language row is consistent in both directions too, which is easy to half-do: README.md links both new translations and all six files link each other.

Twenty checks green. I cannot review Portuguese or Russian prose and did not pretend to; the mechanical invariants are what the guard exists for and they hold.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

2 participants