Guidedog / Documentación 0.2.0

Internacionalización¶

Traduzca la explicación manteniendo su estructura. Guidedog extrae catálogos, fusiona traducciones y construye en el idioma elegido. El original sigue siendo la referencia; una traducción ausente recurre a él sin inventar texto.

Flujo de trabajo¶

Genere las plantillas de mensajes con gettext:
```
guidedog build gettext
```
Escribe una plantilla (.pot) por dominio de texto en _build/gettext. Cada párrafo, título, elemento de lista, celda, leyenda, aviso, término y campo se convierte en un mensaje con su archivo y línea de origen.
Cree o actualice los catálogos de cada idioma, como con sphinx-intl update:
```
guidedog intl update -l de -l fr
```
Los catálogos aparecen en locales/de/LC_MESSAGES/*.po. En ejecuciones posteriores se fusionan las nuevas plantillas, como con msgmerge: se conservan las traducciones, las de mensajes modificados quedan marcadas como fuzzy para revisión y los mensajes retirados permanecen al final como obsoletos (#~), para poder recuperar su traducción.
Rellene cada msgstr. Quite #, fuzzy cuando haya confirmado la traducción; las traducciones fuzzy no se usan.
```
msgid "Hello *world*, see the site_."
msgstr "Hallo *Welt*, siehe site_."
```
Consulte el progreso, como con sphinx-intl stat:
```
guidedog intl stat -l de
```
Compile en ese idioma:
```
guidedog build html -D language=de
guidedog build pdf -D language=de
```
O establezca language = "de" en conf.toml.

Cada libro lleva un sufijo de idioma: manual.pdf pasa a manual-de.pdf. Cada construcción publica una generación completa; usa destinos separados para conservar varias ediciones. Por ejemplo, guidedog build -b pdf docs build/books/de -D language=de para alemán y guidedog build -b pdf docs build/books/en -D language=en para inglés.

Solo se releen los documentos cuyo catálogo cambió, como con cualquier otra entrada. Añadir o quitar un catálogo obliga a releer todos.

guidedog intl acepta las opciones de sphinx-intl: -p DIR para las plantillas (por defecto _build/gettext), -l LANG repetible para los idiomas (por defecto el del proyecto), -d DIR para los catálogos (por defecto el primer locale_dirs), -w N para el ancho de línea (76 por defecto) y --no-obsolete.

Escribir traducciones¶

Un mensaje es el texto de un párrafo, título u otro elemento, incluido su marcado: reStructuredText en .rst y Markdown en .md. La traducción se lee con el mismo marcado y puede mantener énfasis, enlaces y referencias.

Las referencias deben mantenerse. Conserve todas con la misma sintaxis y cambie solo el texto y sus títulos:

msgid "See :ref:`install` and the site_."
msgstr "Siehe :ref:`Installation <install>` und die site_."

Si una traducción omite una referencia, la construcción avisa (inconsistent references in translated message, como Sphinx) y usa la traducción. Si añade una referencia ausente del original, no puede resolverla: avisa y conserva el original. También conserva el original cuando el lector rechaza el marcado traducido, con una advertencia que cita la traducción.

Los anclajes no cambian con el idioma. El título traducido conserva el del original, así que siguen funcionando los enlaces internos y externos.

Opciones¶

Las opciones estándar conservan los nombres y valores de Sphinx. Guidedog añade una exclusión solo para extracción de apéndices que no se traducen.

Opción	Significado
`language`	El idioma de compilación, como `"de"` o `"pt_BR"`.
`locale_dirs`	Ubicaciones de los catálogos, relativas a las fuentes. Cada una contiene `LANGUAGE/LC_MESSAGES/DOMAIN.po` (o un `.mo` compilado). Valor predeterminado: `["locales"]`. Si hay varias, se usa la primera que traduzca el mensaje.
`gettext_compact`	Determina el catálogo de cada documento. Con `true` (predeterminado), cada documento raíz tiene el suyo y los de una carpeta lo comparten (`guide/usage.rst` usa `guide.po`). Con `false`, hay uno por documento. Un nombre hace que todos usen el catálogo de ese nombre.
`gettext_location`	Escribe la ubicación de cada mensaje (`#: ../../index.rst:12`). Predeterminado: `true`.
`gettext_uuid`	Escribe un identificador por aparición, derivado del documento, mensaje y ocurrencia, estable entre builds.
`gettext_auto_build`	Compila cada `.po` a un `.mo` junto a él para otras herramientas. Predeterminado: `true`. Guidedog lee el `.po`.
`gettext_additional_targets`	Contenido adicional: `index` (entradas de índice), `literal-block`, `doctest-block`, `raw` e `image` (texto alternativo).
`gettext_allow_fuzzy_translations`	Usa también traducciones fuzzy. Predeterminado: `false`.
`gettext_exclude_patterns`	Patrones de rutas omitidos solo de la extracción POT, como `["api/**"]`. Predeterminado: `[]`. Los documentos siguen en HTML y PDF.
`gettext_last_translator`, `gettext_language_team`	`Last-Translator` y `Language-Team` de la cabecera de la plantilla.
`figure_language_filename`	Archivo de imagen para el idioma de la construcción. Por defecto `"{root}.{language}{ext}"`: con `language = "de"`, `img/logo.png` pasa a `img/logo.de.png` si existe. Los campos son `{root}`, `{path}`, `{basename}`, `{ext}`, `{docpath}` y `{language}`.
`translation_progress_classes`	Añade la clase `translated` a los elementos traducidos y `untranslated` a los demás (`true`), o solo una de ellas (`"translated"` o `"untranslated"`), para mostrar lo pendiente mediante CSS.

Los textos de la interfaz de Guidedog¶

Guidedog genera algunos textos: títulos de avisos, «Added in version 2.1», «Fig. 1», «Contents», «Previous», «Next», «Navigation» y «Search» del diseño, páginas de búsqueda e índice y «Version» del libro. Proceden del dominio guidedog, consultado en este orden:

locales/LANGUAGE/LC_MESSAGES/guidedog.po del proyecto.
locales/LANGUAGE/LC_MESSAGES/sphinx.po del proyecto, como en Sphinx.
El catálogo integrado para alemán, español, francés, japonés, portugués de Brasil, ruso y chino simplificado.

Los identificadores son los textos ingleses y coinciden con los de Sphinx cuando existe el mismo texto. Así, el sphinx.po del proyecto sigue funcionando. Un guidedog.po propio permite sustituir cualquier texto o añadir un idioma.

Las plantillas traducen con _(), gettext() y ngettext(), como en Sphinx:

<small>{{ _('Previous') }}</small>
{{ _('Last updated on %s.')|format(last_updated) }}

numfig_format, html_title y html_short_title siguen el idioma salvo que se fijen en conf.toml.

Fechas¶

|today|, la fecha del libro y last_updated siguen el formato de Sphinx: today_fmt y html_last_updated_fmt usan strftime; los nombres de meses y días siguen language. Así, %b %d, %Y da «Sep 29, 2026» en inglés y «Sept. 29, 2026» en alemán. Un formato vacío usa _('%b %d, %Y'), traducible en el catálogo. Los nombres de los idiomas anteriores proceden de Unicode CLDR; los demás usan inglés, como Sphinx cuando Babel desconoce el idioma.

La fecha es local y usa la zona horaria local. Establece SOURCE_DATE_EPOCH (segundos desde 1970, en UTC) para construir de forma reproducible con las mismas fechas en todas las máquinas.