| id | LOCALE | |||||
|---|---|---|---|---|---|---|
| title | Saying it in the reader's language | |||||
| status | normative | |||||
| governs |
|
|||||
| documented-by |
|
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.
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
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)
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)
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
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
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)
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
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
-
The letters a question is answered with are not translated.
y,nandaare both the key drawn and the key matched, so a catalog cannot move them: a French reader is told to pressyfor 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.
--traceand 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-localesholds 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_LOCALEcan outrank a choice. It is read first, so a person who exports it has the catalog it names whatever/languagesaved or the settings file says./languagereads no environment, since only the binary's start does (LOCALE-7), so its note says the choice applies unless that variable is set.