Auf dieser Seite

Guidedog / Dokumentation 0.2.0

i18n¶

Package i18n translates Guidedoc documents the way Sphinx does with gettext: it extracts every translatable message of a document into a POT template (Sphinx’s gettext builder), and it replaces each message with its translation from a catalog (Sphinx’s Locale transform), re-parsing the translation as inline markup of the document’s own language. It imports the Guidedoc core and the gettext library only; the reader that parses translations is passed in (gd.Reader.read_inline).

Types

i18n.Compact :: struct¶

Compact is gettext_compact: per top-level directory (true, Sphinx’s default), per document (false), or one catalog of the given name.

mode: enum u8 {Per_Directory, Per_Document, Single}¶

name: string¶: for Single.

i18n.Extract_Options :: struct¶

Extract_Options are the gettext builder’s settings for one document.

targets: Targets ¶: gettext_additional_targets.

location: bool¶: gettext_location: „#: path:line“ for every occurrence.

uuid: bool¶: gettext_uuid: a „#: uuid“ line for every occurrence.

path: string¶: how locations name the main source, e.g. „../../index.rst“.

docname: string¶: the document’s name, e.g. „guide/usage“; seeds the uuids.

base: string¶: included files are named relative to this directory, if set.

i18n.Image_Exists :: struct¶

Image_Exists reports whether an image path, as a document would write it, names a file. The host resolves it against the document’s directory.

procedure: proc(user: rawptr, docname, path: string) -> bool¶

user: rawptr¶

i18n.Image_Localization :: struct¶

Image_Localization is figure_language_filename for the translation pass.

format: string¶: „“ is DEFAULT_FIGURE_FILENAME.

docname: string¶

language: string¶

exists: Image_Exists ¶

i18n.Index_Part :: struct¶

Index_Part is one translatable piece of an index entry line, e.g. „b“ of „single: a; b“. first and length locate it in the line.

text: string¶

first: int¶

length: int¶

i18n.Pot_Header :: struct¶

Pot_Header holds the values of a template’s header, as Sphinx fills them.

project: string¶

version: string¶

copyright: string¶

last_translator: string¶: gettext_last_translator.

language_team: string¶: gettext_language_team.

creation_date: string¶: e.g. „2026-09-29 12:00+0000“.

i18n.Progress :: enum u8¶

Progress is translation_progress_classes: which translatable nodes get the class „translated“ or „untranslated“, so a stylesheet can show what is left to translate.

Translated¶

Untranslated¶

i18n.Progress_Classes :: bit_set[Progress; u8]¶

i18n.Target :: enum u8¶

Target names the extra kinds of content gettext_additional_targets makes translatable.

Index¶: „index“: index entries.

Literal_Block¶: „literal-block“: literal and code blocks, parsed literals.

Doctest_Block¶: „doctest-block“

Raw¶: „raw“

Image¶: „image“: image alt text.

i18n.Targets :: bit_set[Target; u8]¶

i18n.Template :: struct¶

Template collects the messages of one or more documents into a POT catalog, as Sphinx’s gettext builder does: a message found again gains a location instead of a second entry, and messages keep the order of their first occurrence.

catalog: gettext.Catalog ¶

seen: map[string]int¶: msgid -> message index.

uuids: map[string]int¶: uuids per message, for their positions.

i18n.Translation :: struct¶

Translation configures the translation pass, Sphinx’s Locale transform: every translatable node whose message the catalog translates gets the translation. Inline content is re-parsed with read_inline, in the markup the document was written in (read carries the reader’s settings, e.g. a sphinx.Config), and keeps the original’s references; titles keep their anchors. The pass allocates nothing: it takes scratch memory, and registers the catalog’s translation pool as one source, so nodes parsed from a translation have exact spans and diagnostics quote the translation.

catalog: ^gettext.Catalog ¶

read_inline: gd.Read_Inline_Proc ¶

read: gd.Read_Options ¶

policy: gd.Policy ¶

limits: gd.Limits ¶: zero: gd.default_limits().

targets: Targets ¶: gettext_additional_targets.

source_name: string¶: names the translations in diagnostics, e.g. „de/index.po“.

progress: Progress_Classes ¶: translation_progress_classes.

images: Image_Localization ¶: figure_language_filename; applies without a catalog.

translated: int¶

Counts of the last run.

messages replaced.

kept: int¶: translations refused (bad markup or references); warned.

i18n.UI_Problem :: struct¶

UI_Problem is a project catalog that could not be read.

path: string¶

error: gettext.Error ¶

i18n.Unit :: enum u8¶

Unit says how a node carries a message.

None¶

Inline¶: inline content: the source text with its markup; translations re-parse.

Literal¶: the node’s text, verbatim: code, doctest, raw, and math blocks.

Parsed¶: a parsed literal: inline content, only with the literal-block target.

Alt¶: an image’s Alt attribute.

Graphviz¶: diagram alt text and, when requested, its literal source.

Index¶: each part of each index entry.

Caption¶: a toctree’s caption attribute.

Entry¶: a toctree entry’s explicit title.

Meta¶: the values of a meta directive.

Contents¶: a contents directive’s title.

Procedures

i18n.add :: proc(t: ^Template, msgid, location, uuid: string)¶: add adds one occurrence of a message: its location („path:line“, or „“) and uuid. The template copies what it keeps, with its own allocator, so the arguments are borrowed.

i18n.destroy_template :: proc(t: ^Template)¶: destroy_template frees a template and everything added to it, and clears it.

i18n.domain_for :: proc(docname: string, compact: Compact) -> string¶: domain_for returns the catalog (text domain) a document’s messages belong to, as Sphinx’s docname_to_domain does: „guide/usage“ is „guide“ when compact, else „guide/usage“; „index“ is „index“ either way.

i18n.embedded_catalog :: proc(language: string) -> (string, bool)¶: embedded_catalog returns the built-in catalog text for a language, trying it, then its base language (pt_BR, then pt). The text is static, borrowed from the binary; the candidates are made in the temp allocator.

i18n.extract :: proc(t: ^Template, v: gd.View, options: Extract_Options) -> int¶: extract adds every translatable message of a document to the template and returns how many occurrences it found. The template copies the messages with its allocator; the view is borrowed, and scratch strings go to the temp allocator.

i18n.figure_filename :: proc(format, filename, docname, language: string, allocator := context.allocator) -> (string, bool, string)¶: figure_filename is write_figure_filename into a new string allocated with allocator, which the caller owns; on failure the third result explains the format’s problem, in the temp allocator.

i18n.figure_for_language :: proc(format, filename, docname, language: string, exists: Image_Exists, allocator := context.allocator) -> string¶: figure_for_language returns the localized image when it exists, else the image as written, as Sphinx’s search_image_for_language does; with no exists.procedure, no localized image exists. Either way the path is a new string allocated with allocator, which the caller owns.

i18n.fill_labels :: proc(tr: ^gettext.Translator, labels: ^gd.Labels)¶: fill_labels translates every renderer label into labels, for Render_Options.labels.

i18n.format_date :: proc(format: string, moment: datetime.DateTime, language: string, allocator := context.allocator) -> string¶: format_date formats a moment with a strftime format, as Sphinx’s format_date does, with the month and day names of language. The text is allocated with allocator, and the caller owns it.

i18n.index_parts :: proc(line: string, parts: []Index_Part) -> int¶: index_parts splits an index entry line into its translatable pieces, as Sphinx’s split_index_msg does: the entry type and „!“ main marker are kept out of them.

i18n.make_template :: proc(name := "", allocator := context.allocator) -> Template ¶: make_template starts an empty POT catalog named name. It and everything added to it are allocated with allocator; the caller frees them with destroy_template.

i18n.parse_target :: proc(name: string) -> (Target, bool)¶: parse_target returns the target a gettext_additional_targets name stands for.

i18n.set_header :: proc(t: ^Template, h: Pot_Header)¶: set_header gives the template the header Sphinx’s gettext builder writes, copied with the template’s allocator.

i18n.translation_pass :: proc(t: ^Translation) -> gd.Pass ¶: translation_pass returns the pass; t must outlive the transform. The workspace keeps views of the catalog’s pool and of source_name (spans, and reports quoting them), so the catalog and source_name must outlive every use of the document and its reports.

i18n.ui_text :: proc(tr: ^gettext.Translator, msgid: string) -> string¶: ui_text translates one of Guidedog’s words.

i18n.ui_translator :: proc(language: string, dirs: []string, allow_fuzzy := false, allocator := context.allocator) -> (gettext.Translator, []UI_Problem)¶: ui_translator makes the translator of Guidedog’s own words for a language. dirs are the project’s locale directories (absolute). A catalog that fails to parse is left out and reported in problems; the others still apply. The translator and its catalogs are allocated with allocator, and the caller owns them (gettext.destroy_translator); the problems too.

i18n.unit_of :: proc(v: gd.View, id: gd.Node_Id, targets: Targets) -> Unit ¶: unit_of classifies a node as Sphinx’s is_translatable does, with the extra targets. The switch is exhaustive, so a new kind does not compile until it says whether it is translated.

i18n.write_figure_filename :: proc(out: ^gd.Buffer, format, filename, docname, language: string) -> (ok: bool, bad_field: string)¶

write_figure_filename fills a figure_language_filename format for an image path as written in a document, as Sphinx’s get_image_filename_for_language does:

{root}: the path without its extension („img/logo“ of „img/logo.png“);
{path}: its directory with a trailing slash, or „“ („img/“);
{basename}: the file name without directory or extension („logo“);
{ext}: the extension with its dot („.png“);
{docpath}: the document’s directory with a trailing slash, or „“;
{language}: the language.

„{{„ and „}}“ stand for braces. On an unknown field it returns the field’s name.

i18n.write_message :: proc(v: gd.View, id: gd.Node_Id, out: ^gd.Buffer) -> bool¶: write_message writes a node’s msgid as Sphinx makes it from the node’s source: line breaks and the indentation after them become one space, and the ends are trimmed.

i18n.write_template :: proc(t: ^Template, allocator := context.allocator) -> string¶: write_template writes the template as Sphinx lays out a POT file: every location on its own „#:“ line, sorted, then the uuids, and strings broken only after newlines. The text is allocated with allocator, and the caller owns it.

Constants

i18n.DEFAULT_FIGURE_FILENAME :: "{root}.{language}{ext}"¶: DEFAULT_FIGURE_FILENAME is Sphinx’s default figure_language_filename.

i18n.UI_DOMAIN :: "guidedog"¶