このページの内容

Guidedog / ドキュメント 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"