# L10N.md - Specification v1 (Español)

> A convention for repository-resident translation context

Status: Stable
Version: 1
Updated: 2026-05-25
Source: https://github.com/glossia/l10n
License: MIT

---

## Resumen


&lt;p class=&quot;note&quot;&gt;[Pendiente de traducción.] La versión en inglés es la autoritativa hasta que se complete la traducción.&lt;/p&gt;

L10N.md is a convention by which translators provide the context that AI-based translation
systems need before they translate strings. It keeps the machine-readable surface small in
YAML frontmatter and pushes the subtle guidance into ordinary Markdown prose. Documents
live in the repository, are reviewed in pull requests, and are validated against versioned
JSON Schemas. This document specifies the document model, the version 1 schema, and
conformance requirements.


## Estado de este documento


&lt;p class=&quot;note&quot;&gt;[Pendiente de traducción.] La versión en inglés es la autoritativa hasta que se complete la traducción.&lt;/p&gt;

This is version {{ site.spec.version }} of the L10N.md standard and is considered
{{ site.spec.status | lower }}. Sections are normative unless explicitly marked
Informative. A future version may add fields or tighten rules; such changes require a
version increment and a new schema directory and will not silently change the editing
model defined here. A future version is also expected to introduce extension capabilities
that let repository-scoped context be extended with remotely-provided context.
Copyright (c) {{ site.spec.copyright }}; released under the {{ site.spec.license }} license
recorded in the source repository.


## 1. Introducción


&lt;p class=&quot;note&quot;&gt;[Pendiente de traducción.] La versión en inglés es la autoritativa hasta que se complete la traducción.&lt;/p&gt;

AI-based translation systems produce better results when they are given context before
they begin: the source language, the intended tone, brand terminology, and any constraints
that do not fit neatly into key and value pairs. L10N.md is the convention by which
translators record that context as files that live next to the code they describe, so the
systems that translate the strings can read it.

The convention works because it keeps the machine-readable surface tiny and pushes the
judgment into prose. Frontmatter carries structure. Markdown carries nuance. Additional
files appear only when the translation surface actually splits. The same shape holds
whether a project has one document or many.


## 2. Convenciones y terminología


&lt;p class=&quot;note&quot;&gt;[Pendiente de traducción.] La versión en inglés es la autoritativa hasta que se complete la traducción.&lt;/p&gt;

### 2.1 Requirements Notation {:#requirements-notation:}

The key words &lt;span class=&quot;kw&quot;&gt;MUST&lt;/span&gt;, &lt;span class=&quot;kw&quot;&gt;MUST NOT&lt;/span&gt;,
&lt;span class=&quot;kw&quot;&gt;REQUIRED&lt;/span&gt;, &lt;span class=&quot;kw&quot;&gt;SHALL&lt;/span&gt;,
&lt;span class=&quot;kw&quot;&gt;SHALL NOT&lt;/span&gt;, &lt;span class=&quot;kw&quot;&gt;SHOULD&lt;/span&gt;,
&lt;span class=&quot;kw&quot;&gt;SHOULD NOT&lt;/span&gt;, &lt;span class=&quot;kw&quot;&gt;RECOMMENDED&lt;/span&gt;,
&lt;span class=&quot;kw&quot;&gt;NOT RECOMMENDED&lt;/span&gt;, &lt;span class=&quot;kw&quot;&gt;MAY&lt;/span&gt;, and
&lt;span class=&quot;kw&quot;&gt;OPTIONAL&lt;/span&gt; in this document are to be interpreted as described in
BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown
here.

### 2.2 Terminology {:#terminology:}

&lt;dl class=&quot;terms&quot;&gt;
&lt;dt&gt;Repository&lt;/dt&gt;
&lt;dd&gt;The version-controlled project in which L10N documents reside.&lt;/dd&gt;
&lt;dt&gt;Document&lt;/dt&gt;
&lt;dd&gt;A Markdown file that participates in this standard, classified by its repository path.&lt;/dd&gt;
&lt;dt&gt;Frontmatter&lt;/dt&gt;
&lt;dd&gt;An optional leading YAML mapping delimited by lines containing only &lt;code&gt;---&lt;/code&gt;.&lt;/dd&gt;
&lt;dt&gt;Body&lt;/dt&gt;
&lt;dd&gt;The Markdown content following the frontmatter; the prose that carries guidance.&lt;/dd&gt;
&lt;dt&gt;Root document&lt;/dt&gt;
&lt;dd&gt;The repository-wide &lt;code&gt;L10N.md&lt;/code&gt;, also called the global document.&lt;/dd&gt;
&lt;dt&gt;Scoped document&lt;/dt&gt;
&lt;dd&gt;A non-root &lt;code&gt;L10N.md&lt;/code&gt; that adds workflow settings to a subtree.&lt;/dd&gt;
&lt;dt&gt;Locale overlay&lt;/dt&gt;
&lt;dd&gt;A per-language file stored under an &lt;code&gt;L10N/&lt;/code&gt; directory.&lt;/dd&gt;
&lt;dt&gt;Source language&lt;/dt&gt;
&lt;dd&gt;The language strings are authored in, declared by the root document.&lt;/dd&gt;
&lt;dt&gt;Locale identifier&lt;/dt&gt;
&lt;dd&gt;A language tag as defined by [&lt;a href=&quot;#refs-normative&quot;&gt;BCP&amp;nbsp;47&lt;/a&gt;], with an underscore (&lt;code&gt;_&lt;/code&gt;) permitted in place of a hyphen as the subtag separator. See &lt;a href=&quot;#schema-shared&quot;&gt;Section 4.5&lt;/a&gt;. Examples: &lt;code&gt;en&lt;/code&gt;, &lt;code&gt;es&lt;/code&gt;, &lt;code&gt;zh-Hant&lt;/code&gt;, &lt;code&gt;zh_Hant&lt;/code&gt;.&lt;/dd&gt;
&lt;dt&gt;Validation command&lt;/dt&gt;
&lt;dd&gt;
An array of non-empty strings carried by the &lt;code&gt;validation&lt;/code&gt; field. The
translation tool &lt;span class=&quot;kw&quot;&gt;MUST&lt;/span&gt; execute it as a command and arguments
against translated output, treating exit code 0 as pass and any non-zero exit as
failure. Before execution the tool &lt;span class=&quot;kw&quot;&gt;MUST&lt;/span&gt; set these environment
variables:
&lt;ul&gt;
  &lt;li&gt;&lt;code&gt;L10N_SOURCE_PATH&lt;/code&gt; — absolute path to the source file&lt;/li&gt;
  &lt;li&gt;&lt;code&gt;L10N_TARGET_PATH&lt;/code&gt; — absolute path to the translated output file&lt;/li&gt;
  &lt;li&gt;&lt;code&gt;L10N_LOCALE&lt;/code&gt; — the target locale identifier (e.g. &lt;code&gt;es&lt;/code&gt;, &lt;code&gt;ja&lt;/code&gt;)&lt;/li&gt;
  &lt;li&gt;&lt;code&gt;L10N_DOC_PATH&lt;/code&gt; — absolute path to the L10N.md document controlling the scope&lt;/li&gt;
&lt;/ul&gt;
Implementations &lt;span class=&quot;kw&quot;&gt;MAY&lt;/span&gt; provide additional env vars. Validation
commands &lt;span class=&quot;kw&quot;&gt;SHOULD&lt;/span&gt; write diagnostics to stderr; stdout
&lt;span class=&quot;kw&quot;&gt;MAY&lt;/span&gt; be captured as structured output by the tool.
&lt;/dd&gt;
&lt;/dl&gt;


## 3. Modelo de documento


&lt;p class=&quot;note&quot;&gt;[Pendiente de traducción.] La versión en inglés es la autoritativa hasta que se complete la traducción.&lt;/p&gt;

There are three document shapes. They share one mental model: state structure in
frontmatter, explain judgment in prose, and add files only when scope demands it. The
normative contract for each shape is the corresponding JSON Schema in
[Section 4](#schema).

### 3.1 General Requirements {:#general:}

An L10N document &lt;span class=&quot;kw&quot;&gt;MUST&lt;/span&gt; be a Markdown file. It
&lt;span class=&quot;kw&quot;&gt;MAY&lt;/span&gt; begin with a frontmatter block; the content after the
frontmatter is the body. Either side &lt;span class=&quot;kw&quot;&gt;MAY&lt;/span&gt; be empty: the body
&lt;span class=&quot;kw&quot;&gt;MAY&lt;/span&gt; be empty when the frontmatter is sufficient on its own, and
the frontmatter &lt;span class=&quot;kw&quot;&gt;MAY&lt;/span&gt; be absent when the document only adds body
context. Each role&#39;s schema specifies which keys, if any, remain required.

A document&#39;s role &lt;span class=&quot;kw&quot;&gt;MUST&lt;/span&gt; be determined by its repository path, and
the document &lt;span class=&quot;kw&quot;&gt;MUST&lt;/span&gt; validate against the version 1 entry schema
([Section 4.1](#schema-entry)), which requires it to satisfy exactly one of the three
document schemas.

Implementations &lt;span class=&quot;kw&quot;&gt;MUST&lt;/span&gt; ignore frontmatter keys they do not
understand and &lt;span class=&quot;kw&quot;&gt;MUST NOT&lt;/span&gt; reject a document solely because such
keys are present.

### 3.2 Root Document {:#root:}

A repository &lt;span class=&quot;kw&quot;&gt;MAY&lt;/span&gt; contain a root document. When present, its path
&lt;span class=&quot;kw&quot;&gt;MUST&lt;/span&gt; be exactly &lt;code&gt;L10N.md&lt;/code&gt; at the repository root. It
&lt;span class=&quot;kw&quot;&gt;MUST&lt;/span&gt; declare &lt;code&gt;source_language&lt;/code&gt; as a locale identifier,
and &lt;span class=&quot;kw&quot;&gt;MAY&lt;/span&gt; provide a body giving repository-wide guidance such as
tone, brand terminology, and formatting rules. A root document
&lt;span class=&quot;kw&quot;&gt;MAY&lt;/span&gt; also declare the same workflow frontmatter as a scoped
document (&lt;code&gt;validation&lt;/code&gt;, &lt;code&gt;sources&lt;/code&gt;, &lt;code&gt;targets&lt;/code&gt;); this
lets a small repository describe both its language and its translation workflow in a
single file without introducing nested scopes. A conforming
root document satisfies the schema in [Section 4.2](#schema-global); a minimal example
appears in [Appendix A.1](#example-root) and a single-file repository example in
[Appendix A.2](#example-single-repo).

### 3.3 Scoped Document {:#doc-scoped:}

A scoped document is an &lt;code&gt;L10N.md&lt;/code&gt; located in a directory other than the
repository root. Its path &lt;span class=&quot;kw&quot;&gt;MUST&lt;/span&gt; match
&lt;code&gt;^(?!L10N&#92;.md$).+/L10N&#92;.md$&lt;/code&gt;. A scoped document &lt;span class=&quot;kw&quot;&gt;MAY&lt;/span&gt;
declare workflow frontmatter: &lt;code&gt;validation&lt;/code&gt; (an array of non-empty strings),
&lt;code&gt;sources&lt;/code&gt; (a mapping of one or more source patterns to target path
templates), and &lt;code&gt;targets&lt;/code&gt; (an array of one or more locale identifiers).
When any of these are declared, they configure how a
translation tool processes the scope. When none are declared, the document acts purely as
a context override for its subtree. The body &lt;span class=&quot;kw&quot;&gt;MAY&lt;/span&gt; be empty when
the workflow frontmatter alone captures the scope&#39;s intent. The &lt;code&gt;validation&lt;/code&gt;
array, when present, is a command and arguments that the translation tool executes
against translated output (see [Section 2.2](#terminology)). A conforming
scoped document satisfies the schema in [Section 4.3](#schema-scoped); a complete example
appears in [Appendix A.3](#example-scoped).

### 3.4 Locale Overlay {:#doc-locale:}

A locale overlay is a Markdown file whose path &lt;span class=&quot;kw&quot;&gt;MUST&lt;/span&gt; match
&lt;code&gt;^(?:.+/)?L10N/[A-Za-z0-9_-]+&#92;.md$&lt;/code&gt;. It &lt;span class=&quot;kw&quot;&gt;MAY&lt;/span&gt; provide
a body and &lt;span class=&quot;kw&quot;&gt;MAY&lt;/span&gt; declare &lt;code&gt;locale&lt;/code&gt; as a locale
identifier; when &lt;code&gt;locale&lt;/code&gt; is omitted, the locale
&lt;span class=&quot;kw&quot;&gt;SHOULD&lt;/span&gt; be inferred from the file name. An overlay refines
guidance for a single language. It &lt;span class=&quot;kw&quot;&gt;MAY&lt;/span&gt; also declare
&lt;code&gt;validation&lt;/code&gt;; no other frontmatter keys are permitted. When a locale overlay
declares &lt;code&gt;validation&lt;/code&gt;, that command replaces the scope-level or root-level
validation for that language only. A conforming overlay satisfies the schema in
[Section 4.4](#schema-locale); complete examples appear in [Appendix A.4](#example-es)
and [Appendix A.5](#example-ja).


## 4. Esquema del documento, versión 1


&lt;p class=&quot;note&quot;&gt;[Pendiente de traducción.] La versión en inglés es la autoritativa hasta que se complete la traducción.&lt;/p&gt;

The version 1 contract is defined by the JSON Schema files in &lt;code&gt;schemas/v1/&lt;/code&gt;.
Those files are the machine-readable, authoritative form; the tables below state the same
rules so they can be read without parsing JSON Schema. Where a table and its linked file
ever disagree, the file wins.

In every table, &lt;code&gt;path&lt;/code&gt; is the document&#39;s location in the repository (supplied
by the validator, not written in the file) and &lt;code&gt;body&lt;/code&gt; is the Markdown content
after the frontmatter; the remaining properties are the document&#39;s YAML frontmatter keys.
Frontmatter keys not listed here are ignored by conforming implementations.

### 4.1 Entry Point {:#schema-entry:}

A document conforms to this standard when it satisfies exactly one of the three document
schemas that follow: the global document ([Section 4.2](#schema-global)), the scoped
document ([Section 4.3](#schema-scoped)), or the locale overlay
([Section 4.4](#schema-locale)). The entry-point schema expresses this as a
&lt;code&gt;oneOf&lt;/code&gt; over those three.

&lt;p class=&quot;schema-source&quot;&gt;Canonical schema: &lt;a href=&quot;/schemas/v1/l10n-document.schema.json&quot;&gt;&lt;code&gt;schemas/v1/l10n-document.schema.json&lt;/code&gt;&lt;/a&gt;&lt;/p&gt;

### 4.2 Global Document Schema {:#schema-global:}

The repository root &lt;code&gt;L10N.md&lt;/code&gt;. Workflow fields are optional; including them lets a single-file repository describe its language and its translation workflow in one place.

&lt;div class=&quot;table-wrap&quot;&gt;
&lt;table class=&quot;fieldtable&quot;&gt;
&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Property&lt;/th&gt;&lt;th&gt;Required&lt;/th&gt;&lt;th&gt;Type&lt;/th&gt;&lt;th&gt;Rule&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;path&lt;/code&gt;&lt;/td&gt;&lt;td&gt;yes&lt;/td&gt;&lt;td&gt;string&lt;/td&gt;&lt;td&gt;exactly &lt;code&gt;L10N.md&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;source_language&lt;/code&gt;&lt;/td&gt;&lt;td&gt;yes&lt;/td&gt;&lt;td&gt;string&lt;/td&gt;&lt;td&gt;a locale identifier (&lt;a href=&quot;#schema-shared&quot;&gt;Section 4.5&lt;/a&gt;)&lt;/td&gt;&lt;/tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;validation&lt;/code&gt;&lt;/td&gt;&lt;td&gt;no&lt;/td&gt;&lt;td&gt;array of string&lt;/td&gt;&lt;td&gt;the command and its arguments; each element non-empty. See &lt;a href=&quot;#terminology&quot;&gt;Section 2.2&lt;/a&gt;.&lt;/td&gt;&lt;/tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;sources&lt;/code&gt;&lt;/td&gt;&lt;td&gt;no&lt;/td&gt;&lt;td&gt;object&lt;/td&gt;&lt;td&gt;one or more entries; keys are non-empty source path patterns, values are non-empty target path templates (typically containing &lt;code&gt;{locale}&lt;/code&gt;)&lt;/td&gt;&lt;/tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;targets&lt;/code&gt;&lt;/td&gt;&lt;td&gt;no&lt;/td&gt;&lt;td&gt;array of string&lt;/td&gt;&lt;td&gt;one or more locale identifiers; duplicates are not permitted&lt;/td&gt;&lt;/tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;body&lt;/code&gt;&lt;/td&gt;&lt;td&gt;yes&lt;/td&gt;&lt;td&gt;string&lt;/td&gt;&lt;td&gt;Markdown prose; may be empty&lt;/td&gt;&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;/div&gt;

&lt;p class=&quot;schema-source&quot;&gt;Canonical schema: &lt;a href=&quot;/schemas/v1/global-document.schema.json&quot;&gt;&lt;code&gt;schemas/v1/global-document.schema.json&lt;/code&gt;&lt;/a&gt;&lt;/p&gt;

### 4.3 Scoped Document Schema {:#schema-scoped:}

A non-root &lt;code&gt;L10N.md&lt;/code&gt;. Workflow fields are optional; when omitted, the document acts as a context override for its subtree.

&lt;div class=&quot;table-wrap&quot;&gt;
&lt;table class=&quot;fieldtable&quot;&gt;
&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Property&lt;/th&gt;&lt;th&gt;Required&lt;/th&gt;&lt;th&gt;Type&lt;/th&gt;&lt;th&gt;Rule&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;path&lt;/code&gt;&lt;/td&gt;&lt;td&gt;yes&lt;/td&gt;&lt;td&gt;string&lt;/td&gt;&lt;td&gt;matches &lt;code&gt;^(?!L10N&#92;.md$).+/L10N&#92;.md$&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;validation&lt;/code&gt;&lt;/td&gt;&lt;td&gt;no&lt;/td&gt;&lt;td&gt;array of string&lt;/td&gt;&lt;td&gt;the command and its arguments; each element non-empty. See &lt;a href=&quot;#terminology&quot;&gt;Section 2.2&lt;/a&gt;.&lt;/td&gt;&lt;/tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;sources&lt;/code&gt;&lt;/td&gt;&lt;td&gt;no&lt;/td&gt;&lt;td&gt;object&lt;/td&gt;&lt;td&gt;one or more entries; keys are non-empty source path patterns, values are non-empty target path templates (typically containing &lt;code&gt;{locale}&lt;/code&gt;)&lt;/td&gt;&lt;/tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;targets&lt;/code&gt;&lt;/td&gt;&lt;td&gt;no&lt;/td&gt;&lt;td&gt;array of string&lt;/td&gt;&lt;td&gt;one or more locale identifiers; duplicates are not permitted&lt;/td&gt;&lt;/tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;body&lt;/code&gt;&lt;/td&gt;&lt;td&gt;yes&lt;/td&gt;&lt;td&gt;string&lt;/td&gt;&lt;td&gt;Markdown prose; may be empty&lt;/td&gt;&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;/div&gt;

&lt;p class=&quot;schema-source&quot;&gt;Canonical schema: &lt;a href=&quot;/schemas/v1/scoped-document.schema.json&quot;&gt;&lt;code&gt;schemas/v1/scoped-document.schema.json&lt;/code&gt;&lt;/a&gt;&lt;/p&gt;

### 4.4 Locale Overlay Schema {:#schema-locale:}

A per-language file under an &lt;code&gt;L10N/&lt;/code&gt; directory.

&lt;div class=&quot;table-wrap&quot;&gt;
&lt;table class=&quot;fieldtable&quot;&gt;
&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Property&lt;/th&gt;&lt;th&gt;Required&lt;/th&gt;&lt;th&gt;Type&lt;/th&gt;&lt;th&gt;Rule&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;path&lt;/code&gt;&lt;/td&gt;&lt;td&gt;yes&lt;/td&gt;&lt;td&gt;string&lt;/td&gt;&lt;td&gt;matches &lt;code&gt;^(?:.+/)?L10N/[A-Za-z0-9_-]+&#92;.md$&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;locale&lt;/code&gt;&lt;/td&gt;&lt;td&gt;no&lt;/td&gt;&lt;td&gt;string&lt;/td&gt;&lt;td&gt;a locale identifier; when present, equals the file name&lt;/td&gt;&lt;/tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;validation&lt;/code&gt;&lt;/td&gt;&lt;td&gt;no&lt;/td&gt;&lt;td&gt;array of string&lt;/td&gt;&lt;td&gt;same as above&lt;/td&gt;&lt;/tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;body&lt;/code&gt;&lt;/td&gt;&lt;td&gt;yes&lt;/td&gt;&lt;td&gt;string&lt;/td&gt;&lt;td&gt;Markdown prose; may be empty&lt;/td&gt;&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;/div&gt;

&lt;p class=&quot;schema-source&quot;&gt;Canonical schema: &lt;a href=&quot;/schemas/v1/locale-overlay.schema.json&quot;&gt;&lt;code&gt;schemas/v1/locale-overlay.schema.json&lt;/code&gt;&lt;/a&gt;&lt;/p&gt;

### 4.5 Shared Definitions {:#schema-shared:}

Reusable definitions referenced by the schemas above. A locale identifier in this
standard is a language tag as defined by [[BCP&amp;nbsp;47](#refs-normative)], with one
accommodation: an underscore (&lt;code&gt;_&lt;/code&gt;) &lt;span class=&quot;kw&quot;&gt;MAY&lt;/span&gt; be used in
place of a hyphen as the subtag separator, so that identifiers can serve as filenames
and directory names on systems and tools that disallow hyphens. The
&lt;code&gt;localeIdentifier&lt;/code&gt; pattern below is a syntactic approximation that accepts
well-formed [BCP47] tags and their underscore-separated equivalents; consuming
implementations &lt;span class=&quot;kw&quot;&gt;SHOULD&lt;/span&gt; additionally validate against [BCP47]
when stricter checking is required.

&lt;div class=&quot;table-wrap&quot;&gt;
&lt;table class=&quot;fieldtable&quot;&gt;
&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Definition&lt;/th&gt;&lt;th&gt;Type&lt;/th&gt;&lt;th&gt;Rule&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;localeIdentifier&lt;/code&gt;&lt;/td&gt;&lt;td&gt;string&lt;/td&gt;&lt;td&gt;a language tag per [&lt;a href=&quot;#refs-normative&quot;&gt;BCP&amp;nbsp;47&lt;/a&gt;], with &lt;code&gt;_&lt;/code&gt; permitted as a subtag separator; approximated by &lt;code&gt;^[A-Za-z]{2,3}(?:[-_][A-Za-z0-9]{2,8})*$&lt;/code&gt;. Examples: &lt;code&gt;en&lt;/code&gt;, &lt;code&gt;es&lt;/code&gt;, &lt;code&gt;ja&lt;/code&gt;, &lt;code&gt;zh-Hant&lt;/code&gt;, &lt;code&gt;zh_Hant&lt;/code&gt;.&lt;/td&gt;&lt;/tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;nonEmptyString&lt;/code&gt;&lt;/td&gt;&lt;td&gt;string&lt;/td&gt;&lt;td&gt;at least one character&lt;/td&gt;&lt;/tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;nonEmptyStringArray&lt;/code&gt;&lt;/td&gt;&lt;td&gt;array&lt;/td&gt;&lt;td&gt;each element is a &lt;code&gt;nonEmptyString&lt;/code&gt;; minimum one element&lt;/td&gt;&lt;/tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;markdownBody&lt;/code&gt;&lt;/td&gt;&lt;td&gt;string&lt;/td&gt;&lt;td&gt;any string, including empty&lt;/td&gt;&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;/div&gt;

&lt;p class=&quot;schema-source&quot;&gt;Canonical schema: &lt;a href=&quot;/schemas/v1/shared.schema.json&quot;&gt;&lt;code&gt;schemas/v1/shared.schema.json&lt;/code&gt;&lt;/a&gt;&lt;/p&gt;


## 5. Flujo de validación


&lt;p class=&quot;note&quot;&gt;[Pendiente de traducción.] La versión en inglés es la autoritativa hasta que se complete la traducción.&lt;/p&gt;

&lt;p class=&quot;note&quot;&gt;This section is informative.&lt;/p&gt;

An L10N document &lt;span class=&quot;kw&quot;&gt;MAY&lt;/span&gt; declare &lt;code&gt;validation&lt;/code&gt; in its
frontmatter to specify a command the translation tool runs after translation is
complete. The typical use is for developers to provide a script that checks the
LLM-generated translation against project-specific rules (length limits, glossary
compliance, balance constraints, formatting invariants) before the output is accepted.

The &lt;code&gt;validation&lt;/code&gt; value &lt;span class=&quot;kw&quot;&gt;MUST&lt;/span&gt; be an array of non-empty
strings. The first element is the command; subsequent elements are its arguments. The
shell is not involved — the array elements map directly to OS-level
&lt;code&gt;exec&lt;/code&gt; arguments. The translation tool &lt;span class=&quot;kw&quot;&gt;MUST&lt;/span&gt; execute
the command with the directory containing the L10N.md document that declared the
&lt;code&gt;validation&lt;/code&gt; as the working directory, or document a different
default.

Before execution, the tool &lt;span class=&quot;kw&quot;&gt;MUST&lt;/span&gt; set the following environment
variables:

&lt;ul&gt;
  &lt;li&gt;&lt;code&gt;L10N_SOURCE_PATH&lt;/code&gt; — absolute path to the source file&lt;/li&gt;
  &lt;li&gt;&lt;code&gt;L10N_TARGET_PATH&lt;/code&gt; — absolute path to the translated output file&lt;/li&gt;
  &lt;li&gt;&lt;code&gt;L10N_LOCALE&lt;/code&gt; — the target locale identifier (e.g. &lt;code&gt;es&lt;/code&gt;, &lt;code&gt;ja&lt;/code&gt;)&lt;/li&gt;
  &lt;li&gt;&lt;code&gt;L10N_DOC_PATH&lt;/code&gt; — absolute path to the L10N.md document whose
  &lt;code&gt;validation&lt;/code&gt; triggered the command&lt;/li&gt;
&lt;/ul&gt;

Implementations &lt;span class=&quot;kw&quot;&gt;MAY&lt;/span&gt; provide additional environment variables.
The command &lt;span class=&quot;kw&quot;&gt;MUST&lt;/span&gt; exit with code 0 to signal that the
translation is acceptable; any non-zero exit &lt;span class=&quot;kw&quot;&gt;MUST&lt;/span&gt; be treated as
a failure. The tool &lt;span class=&quot;kw&quot;&gt;SHOULD&lt;/span&gt; pass the command&#39;s stderr back to
the translation agent so it can incorporate the diagnostics into a retry, and
&lt;span class=&quot;kw&quot;&gt;MAY&lt;/span&gt; capture stdout for structured reporting.

Validation commands compose through replacement: a scoped document&#39;s
&lt;code&gt;validation&lt;/code&gt; replaces the root-level command for that scope&#39;s files, and a
locale overlay&#39;s &lt;code&gt;validation&lt;/code&gt; replaces the scoped (or root) command for that
language only. When no &lt;code&gt;validation&lt;/code&gt; is declared at any level, the translation
tool &lt;span class=&quot;kw&quot;&gt;MAY&lt;/span&gt; apply built-in checks inferred from file type (e.g.
Markdown parse validity, gettext &lt;code&gt;.mo&lt;/code&gt; compilation).


## 6. Conformidad


&lt;p class=&quot;note&quot;&gt;[Pendiente de traducción.] La versión en inglés es la autoritativa hasta que se complete la traducción.&lt;/p&gt;

A *conforming document* is a Markdown file whose path matches one of the document
patterns in [Section 3](#model) and that validates against the version 1 entry
schema ([Section 4.1](#schema-entry)).

A *conforming repository* &lt;span class=&quot;kw&quot;&gt;MUST&lt;/span&gt; contain at most one root
document, located at &lt;code&gt;L10N.md&lt;/code&gt;, and every file whose path matches a document
pattern &lt;span class=&quot;kw&quot;&gt;MUST&lt;/span&gt; be a conforming document. A validating tool
&lt;span class=&quot;kw&quot;&gt;MUST&lt;/span&gt; treat a schema validation failure as an error and
&lt;span class=&quot;kw&quot;&gt;SHOULD&lt;/span&gt; report the offending path and the failing constraint.


## 7. Referencias


&lt;p class=&quot;note&quot;&gt;[Pendiente de traducción.] La versión en inglés es la autoritativa hasta que se complete la traducción.&lt;/p&gt;

### 7.1 Normative References {:#refs-normative:}

&lt;dl class=&quot;refs&quot;&gt;
&lt;dt&gt;[RFC2119]&lt;/dt&gt;
&lt;dd&gt;Bradner, S., &quot;Key words for use in RFCs to Indicate Requirement Levels&quot;, BCP 14, RFC 2119, March 1997.&lt;/dd&gt;
&lt;dt&gt;[RFC8174]&lt;/dt&gt;
&lt;dd&gt;Leiba, B., &quot;Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words&quot;, BCP 14, RFC 8174, May 2017.&lt;/dd&gt;
&lt;dt&gt;[BCP47]&lt;/dt&gt;
&lt;dd&gt;Phillips, A., and M. Davis, &quot;Tags for Identifying Languages&quot;, BCP 47, RFC 5646, September 2009.&lt;/dd&gt;
&lt;dt&gt;[JSON-SCHEMA]&lt;/dt&gt;
&lt;dd&gt;Wright, A., et al., &quot;JSON Schema: A Media Type for Describing JSON Documents&quot;, Draft 2020-12.&lt;/dd&gt;
&lt;dt&gt;[YAML]&lt;/dt&gt;
&lt;dd&gt;Ben-Kiki, O., et al., &quot;YAML Ain&#39;t Markup Language (YAML) Version 1.2&quot;.&lt;/dd&gt;
&lt;dt&gt;[COMMONMARK]&lt;/dt&gt;
&lt;dd&gt;MacFarlane, J., &quot;CommonMark Spec&quot;.&lt;/dd&gt;
&lt;/dl&gt;

### 7.2 Informative References {:#refs-informative:}

&lt;dl class=&quot;refs&quot;&gt;
&lt;dt&gt;[MISE]&lt;/dt&gt;
&lt;dd&gt;&quot;mise-en-place&quot;, &lt;a href=&quot;https://mise.jdx.dev/&quot;&gt;https://mise.jdx.dev/&lt;/a&gt;.&lt;/dd&gt;
&lt;dt&gt;[AUBE]&lt;/dt&gt;
&lt;dd&gt;&quot;aube, a fast Node.js package manager&quot;, &lt;a href=&quot;https://aube.en.dev/&quot;&gt;https://aube.en.dev/&lt;/a&gt;.&lt;/dd&gt;
&lt;dt&gt;[ELEVENTY]&lt;/dt&gt;
&lt;dd&gt;&quot;Eleventy&quot;, &lt;a href=&quot;https://www.11ty.dev/&quot;&gt;https://www.11ty.dev/&lt;/a&gt;.&lt;/dd&gt;
&lt;/dl&gt;


## Appendix A. Ejemplos


&lt;p class=&quot;note&quot;&gt;[Pendiente de traducción.] La versión en inglés es la autoritativa hasta que se complete la traducción.&lt;/p&gt;

&lt;p class=&quot;note&quot;&gt;This appendix is informative.&lt;/p&gt;

### A.1 Minimal Root Document {:#example-root:}

&lt;figure class=&quot;listing&quot;&gt;
&lt;figcaption&gt;Listing 2. Canonical root &lt;code&gt;L10N.md&lt;/code&gt;&lt;/figcaption&gt;

```
{{ reference.standard }}
```

&lt;/figure&gt;

### A.2 Single-File Repository Root {:#example-single-repo:}

A root document that also carries workflow frontmatter, so the repository needs no nested scopes.

&lt;figure class=&quot;listing&quot;&gt;
&lt;figcaption&gt;Listing 3. &lt;code&gt;examples/single-repo/L10N.md&lt;/code&gt;&lt;/figcaption&gt;

```
{{ reference.examples.singleRepo }}
```

&lt;/figure&gt;

### A.3 Scoped Document {:#example-scoped:}

&lt;figure class=&quot;listing&quot;&gt;
&lt;figcaption&gt;Listing 4. &lt;code&gt;examples/app/L10N.md&lt;/code&gt;&lt;/figcaption&gt;

```
{{ reference.examples.scoped }}
```

&lt;/figure&gt;

### A.4 Spanish Locale Overlay {:#example-es:}

&lt;figure class=&quot;listing&quot;&gt;
&lt;figcaption&gt;Listing 5. &lt;code&gt;examples/app/L10N/es.md&lt;/code&gt;&lt;/figcaption&gt;

```
{{ reference.examples.es }}
```

&lt;/figure&gt;

### A.5 Japanese Locale Overlay {:#example-ja:}

&lt;figure class=&quot;listing&quot;&gt;
&lt;figcaption&gt;Listing 6. &lt;code&gt;examples/app/L10N/ja.md&lt;/code&gt;&lt;/figcaption&gt;

```
{{ reference.examples.ja }}
```

&lt;/figure&gt;