Skip to content

Latest commit

 

History

History
249 lines (206 loc) · 17 KB

localization.md

File metadata and controls

249 lines (206 loc) · 17 KB
id LOCALE
title Saying it in the reader's language
status normative
governs
crates/i18n/build.rs
crates/i18n/src/*.rs
crates/i18n/locales/*.ftl
crates/agent/tests/audience.rs
crates/ui-bridge/src/language.rs
documented-by
docs/website/docs/customize/configuration.md
docs/website/docs/customize/language.md

Scope

Every word this program says to a person, where those words live, and which of them may change with the reader's language.

There are two audiences and only one of them is a reader. A person watching the terminal is one; the planner is the other, and what it is sent is an interface rather than prose. This spec is about the first. It says nothing about what the planner is sent beyond forbidding a translation from reaching it.

Clauses

LOCALE-1: only what a person reads is translated

A catalog holds the interface: the prompts, the confirmations, the status lines, the errors a person is shown. It does not hold a tool's description, the preamble, the instruction a processor is given, or the sentence a refused tool answers with. Those go to the planner, and the words in them are load-bearing on what it does.

Why. Translating them would make the agent behave differently in French, which is a change nobody would find by reading the French. The words the planner reads are pinned by the specs that govern each tool, and a catalog is not one of them. The line is the audience, not the crate: a string in bravebot-agent that reaches the screen is a message, and a string in bravebot-tui that reaches a request is not.

verified-by: bravebot_agent::audience::what_the_planner_reads_is_not_taken_from_a_catalog verified-by: bravebot_agent::audience::a_lookup_is_recognised_however_it_is_written

LOCALE-2: a message is chosen by a name written in the source, never by a value

There is no way to write a lookup whose result depends on something computed while running, so there is no path by which content the agent was handed can decide what is said to the person watching. A name no catalog defines does not fall back and does not put a key on the screen: it fails to build, at the line that wrote it.

Why. A message chosen by a value is a branch, and untrusted bytes do not get to take one. This is the same rule the rest of the system runs on, applied to the one remaining surface that would otherwise look harmless: the driver deciding which of its own sentences to print is still the driver deciding.

verified-by: by-construction (the lookup has one arm per message and no arm accepting an expression, so a key computed at run time does not compile)

LOCALE-3: the reference catalog owns the message set and every argument

en-US is the reference. A translation may say each message differently and may leave one out, falling back. It may not add a message the reference does not have, read an argument the reference does not pass, or put an argument in a plural the reference states in the singular.

Why. Argument names and kinds are what the call sites compile against. A translation that could change them could break the build of a program nobody had touched, in a language the person who broke it does not read.

verified-by: by-construction (a catalog that adds a message, reads an unknown argument, or introduces a select fails the build that would have shipped it)

LOCALE-4: a locale request widens to the language, then to the reference

The catalog named for exactly the locale asked for, else any catalog in the same language, else the reference. What a shell appends to say which encoding and which modifier is not part of the name, and the POSIX C locale asks for no catalog at all.

verified-by: bravebot_i18n::lib::a_request_takes_the_catalog_of_that_exact_name verified-by: bravebot_i18n::lib::a_request_with_no_catalog_of_its_own_takes_one_in_its_language verified-by: bravebot_i18n::lib::a_bare_language_takes_a_catalog_in_that_language verified-by: bravebot_i18n::lib::a_language_that_did_not_ship_falls_back verified-by: bravebot_i18n::lib::the_encoding_and_modifier_a_shell_appends_are_not_part_of_the_tag verified-by: bravebot_i18n::lib::a_modifier_with_no_encoding_before_it_is_not_part_of_the_tag verified-by: bravebot_i18n::lib::the_posix_locale_asks_for_no_catalog verified-by: bravebot_i18n::lib::the_posix_locale_is_not_read_as_a_language_even_where_a_tag_spells_it

LOCALE-5: a plural is formed by the rules of the language it is written in

A message that counts states its own forms, and which one is used is decided by the rules of the language the catalog those forms came from is written in, which for a message a translation leaves out is the reference. A language whose rules are not written down cannot ship a message that counts. The reference may say its forms alike where its own language does not tell them apart, so that a translation can tell them apart.

Why. Borrowing English's rule is how a translation comes out reading correctly for one and wrongly for everything else, which is a defect only a speaker of that language can see and which no review in English will catch.

verified-by: bravebot_i18n::lib::a_plural_select_picks_the_variant_the_language_calls_for verified-by: bravebot_i18n::generate::a_select_whose_forms_say_the_same_is_generated_as_that_text verified-by: bravebot_i18n::lib::a_language_with_a_plural_rule_is_the_only_kind_a_select_may_ship_in verified-by: bravebot_i18n::generate::a_message_a_translation_omits_is_pluralised_by_the_language_it_is_written_in verified-by: bravebot_i18n::generate::a_message_a_translation_has_is_pluralised_by_that_translation_s_rules verified-by: bravebot_i18n::generate::a_select_in_a_language_with_no_plural_rule_is_found

LOCALE-6: no catalog is read while the agent is running

Catalogs are turned into code before the binary exists. A running process holds finished text and nothing that parses, matches, or interpolates a catalog.

Why. A message format is a small language, and an interpreter for one, running in the process whose whole premise is that it does not interpret what it was given, is the sort of thing that is only ever noticed afterwards.

verified-by: by-construction (the build script writes Rust, and the crate links no parser: the catalog module is declared #[cfg(test)] in crates/i18n/src/lib.rs and the build script reaches the file through an include! of its own, so what ships are string constants and the code that concatenates them; the absence is pinned by the compile_fail doctest calling bravebot_i18n::catalog::parse in crates/i18n/src/lib.rs, beside an ordinary doctest calling the sibling plural::category that does ship, since a compile_fail block alone passes for any compile error at all)

LOCALE-7: the locale is chosen once, by the program, and not by the library

Nothing about the environment reaches a message until a binary says so, and it says so once, before anything is drawn. Anything that did not ask reads the reference. The terminal chooses from the environment and from what the person said (LOCALE-8), and so does the desktop window, which asks the bridge once before its first paint and reads the ui- messages of that catalog, generated from the same files, until it is started again. bravebot-rpc chooses en-US for its own notes whatever the environment says, because the window shows the notes the bridge builds as they stand. Of the window's own words, only the ui- messages are read from a catalog; the rest of its chrome is in English.

Why. A library that consulted the environment the first time something needed a word would make the output of every test depend on the machine it ran on, and a test that pins what a person sees is worth nothing if two people running it see different things.

verified-by: bravebot_i18n::lib::a_process_that_never_chose_a_locale_reads_the_reference verified-by: bravebot_i18n::lib::a_process_whose_environment_names_a_language_still_reads_the_reference_until_asked verified-by: bravebot_i18n::sizes_in_french::the_size_notes_are_said_in_the_chosen_catalog verified-by: bravebot_ui_bridge::english_notes::a_note_for_the_window_is_in_english_whatever_the_machine_says verified-by: bravebot_i18n::lib::the_catalog_chosen_for_a_window_follows_the_order_the_terminal_starts_by verified-by: bravebot_i18n::typescript::the_window_s_messages_are_what_the_catalogs_say verified-by: bravebot_i18n::typescript::only_messages_named_for_the_window_are_written verified-by: bravebot_i18n::typescript::a_message_a_translation_omits_is_the_reference_s verified-by: bravebot_i18n::typescript::a_plural_is_formed_by_the_rules_of_the_catalog_it_is_written_in verified-by: bravebot_i18n::typescript::a_quote_or_backslash_in_a_message_stays_text verified-by: bravebot_ui_bridge::history::a_failed_turn_on_the_account_is_sent_in_english_on_a_machine_set_to_french verified-by: bravebot_ui_bridge::history::the_narrations_for_a_summary_the_account_could_not_make_are_in_english_on_a_machine_set_to_french

LOCALE-8: what the person said outranks the shell, and only their own file says it

Before anything is drawn the terminal takes the first of these that names something: BRAVEBOT_LOCALE, the tag /language saved in ~/.bravebot/language, the language key of ~/.bravebot/settings.json, then LC_ALL, LC_MESSAGES and LANG. A blank value names nothing, and so does auto in the saved tag or the key, which is how a person hands the question to the next source. The key is read from the person's own file alone, ahead of the command line. A project or local settings file and a file --settings names cannot set it, and doctor reports each one that tried and a value no catalog answers. The value is matched against the catalogs that shipped by the widening of LOCALE-4, so it chooses among finished catalogs and names no message (LOCALE-2, LOCALE-6).

/language <tag> saves the tag of the catalog that answered the word and refuses a word no catalog answers, naming the catalogs there are. The choice applies from the next start, since the catalog is chosen once (LOCALE-7). /language auto removes the saved tag. A session that records nothing saves nothing, and says so. The desktop window's language picker saves and removes the same file by the same rules, and says when BRAVEBOT_LOCALE outranks it. Where none of the sources above names anything, the window, and only the window, takes the first of the operating system's preferred languages a catalog answers, and the reference where none does: an app opened from a launcher usually has no LANG.

Why. A person's language belongs to the person and has to be settable where a shell is not: a program started from a launcher has no shell profile to edit. A project's file is written by whoever wrote the project, and the catalog is one choice for the whole process, made before the command line says whether that file may be read. BRAVEBOT_LOCALE stays first because a launch can give it for itself, and the tests that run the binary pin their catalog with it. What /language saved outranks the file because it is the later act, as a saved model or effort level outranks the person's own file.

verified-by: bravebot_i18n::lib::a_language_the_person_wrote_outranks_the_posix_variables verified-by: bravebot_i18n::lib::without_a_choice_the_posix_variables_answer_in_their_order verified-by: bravebot_i18n::lib::what_the_person_picked_outranks_what_the_settings_file_says verified-by: bravebot_i18n::lib::the_variable_made_for_this_program_outranks_what_the_person_said verified-by: bravebot_i18n::lib::a_blank_or_auto_choice_leaves_the_question_to_the_next_source verified-by: bravebot_i18n::lib::a_language_that_did_not_ship_is_found_by_nothing_though_it_resolves_to_the_reference verified-by: bravebot_config::settings::only_the_persons_own_file_can_name_the_language verified-by: bravebot_config::settings::the_language_read_ahead_of_the_command_line_is_the_home_layers verified-by: bravebot_config::settings::a_language_that_is_blank_or_not_a_string_names_nothing verified-by: bravebot_session::store::a_saved_language_is_read_back_replaced_and_forgotten verified-by: bravebot_session::store::a_pipe_where_the_language_file_should_be_is_no_choice_and_holds_nothing_up verified-by: bravebot_session::store::a_language_file_grown_large_still_answers_with_its_first_line verified-by: bravebot_tui::app::the_language_command_carries_its_word verified-by: bravebot_ui_bridge::language::a_language_chosen_in_the_window_is_saved_where_the_terminal_reads_it_and_read_back verified-by: bravebot_ui_bridge::language::automatic_removes_the_saved_choice verified-by: bravebot_ui_bridge::language::a_word_no_catalog_answers_is_refused_and_nothing_is_saved verified-by: bravebot_ui_bridge::language::the_variable_made_for_this_program_is_reported_as_outranking_the_choice verified-by: bravebot_ui_bridge::language::a_choice_that_could_not_be_saved_says_so_and_changes_nothing verified-by: bravebot_ui_bridge::language::with_nothing_else_named_the_systems_languages_choose_the_window_s_catalog verified-by: bravebot_i18n::lib::a_window_with_nothing_named_takes_the_first_system_language_a_catalog_answers verified-by: bravebot_tui::app::a_language_a_catalog_answers_is_saved_under_the_catalogs_own_tag verified-by: bravebot_tui::app::a_language_no_catalog_answers_is_refused_and_not_saved verified-by: bravebot_tui::app::auto_gives_the_choice_back_and_leaves_no_file verified-by: bravebot_tui::app::a_session_that_keeps_nothing_says_the_language_was_not_saved verified-by: bravebot_tui::app::the_bare_language_command_says_what_is_in_use_and_what_was_saved verified-by: bravebot_cli::running::a_language_in_the_settings_file_outranks_what_the_shell_says verified-by: bravebot_cli::running::without_the_key_the_shell_still_chooses_the_language verified-by: bravebot_cli::running::a_language_saved_by_the_command_outranks_the_settings_file verified-by: bravebot_cli::running::the_variable_made_for_this_program_outranks_the_settings_file_and_the_saved_choice verified-by: bravebot_cli::running::a_checkouts_settings_files_cannot_choose_the_language verified-by: bravebot_cli::running::doctor_names_a_language_a_checkout_wrote verified-by: bravebot_cli::running::doctor_names_a_language_no_catalog_answers_and_only_that

Known costs

  • The letters a question is answered with are not translated. y, n and a are both the key drawn and the key matched, so a catalog cannot move them: a French reader is told to press y for oui. Changing that means deciding per language which letters a prompt answers to, which is a change to what the interface listens for rather than to what it says.

  • Numbers are not fully formatted for the locale. A catalog says what separates a whole number from its fraction, which covers the two figures in the interface that have one. Digit grouping, alternative numerals, and percent and currency forms are not done: each needs the CLDR tables, and a partial imitation of them reads worse than a plain number because it is wrong only sometimes.

  • The words on the working indicator are not in a catalog. They are chosen for tone and variety rather than for meaning, and translating one word for word keeps neither. A language supplies its own list, of its own length, in the interface rather than in a catalog, and one that has not supplied any is shown English.

  • The audit trail is not translated. --trace and the trail the interface shows are a record of what the system decided, in fixed columns, holding gate and capability names that are identifiers rather than words. It is read the way a log is read, and by somebody comparing it against the specs that use those same names, so it stays in one language. See trace.md.

  • A translation may lag the reference, and what it lacks is written down. A catalog with fewer messages than the reference builds, and the messages it does not have are shown in English, pluralised by English's rules. Nothing fails over the gap itself, because a translation that had to be finished before it could be used would never be started. What fails is a gap nobody recorded: untranslated-messages.txt lists them, and make check-locales holds the two to each other in both directions, so adding a message without translating it is a line in a diff rather than a warning in a build that passed. The build still counts the gap as it compiles the catalogs, and that count is a convenience rather than the check: a warning is silent on a build that did not re-run.

  • BRAVEBOT_LOCALE can outrank a choice. It is read first, so a person who exports it has the catalog it names whatever /language saved or the settings file says. /language reads no environment, since only the binary's start does (LOCALE-7), so its note says the choice applies unless that variable is set.