Loading...

This is taking longer than expected.

Coding standards

Documentation

These are the standards the analyzer applies. Every rule states what it checks and why it exists.

All standards

Documentation Is Written in English

Every Markdown file in the repository is written in English. A repository has one working language, and documentation that drifts into another splits its readers: the next person to open the file may not be the one who wrote it.
This covers the root README.md, project documentation under docs/, guides, standards, and any instruction file an assistant reads.
Two things are not violations of it.
A file inside a locale folder is written in that locale's language. A path segment naming a language — es, en, pt — declares what the file holds, and a Spanish document under es/ is doing exactly its job. English remains the source.

handbook/onboarding.md              English, the source
handbook/es/onboarding.md           Spanish, translated from it

A document written for the client is written in the client's language. A feature analysis under an analysis/ folder is a deliverable someone outside the team reads and approves, so it follows that reader, not the repository. The same goes for any generated document handed to a user.
Everything else defaults to English, including a file that only the team will ever read. "Only I will read this" is how a repository ends up in two languages.
The validator checks each Markdown prose block independently. Outside the exceptions above, a block containing more than three distinct Spanish words is Spanish prose and is a violation, even when the rest of the document is English. Code fences and inline code are examples, not documentation prose, so they are excluded.
When a document has to change language, move it and translate it in separate changes. A diff that relocates and rewrites at once cannot be checked: a paragraph lost in the move looks exactly like a paragraph reworded in the translation.

A Translation Says What Its Source Says

A translated document and its source are one document in two languages, not two documents. Correcting a translation's wording is welcome: a clumsy sentence, a term nobody uses, a phrasing that reads as translated rather than written. Changing what it states is not.
Adding a step the English does not have, dropping a warning, softening a limitation, or updating a translated page while leaving its source behind all produce two documents that disagree, and a reader has no way to tell which one is true.
When the content itself has to change, change the English and translate it again. The source moves first, always.

Correct    — the English says the code arrives by SMS or by call;
             the Spanish is reworded so it reads naturally, saying the same thing
Incorrect  — the English says by SMS or by call;
             the Spanish adds "or by WhatsApp" because it happens to be true

Help documents carry a fingerprint of the English they were written from, so php artisan help:stamp --check can report a translation whose source has moved on.

Weblabor Logo Developed by Weblabor