Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

update some of the diagnostic translations info #1711

Merged
merged 6 commits into from
Jan 20, 2024
Merged

update some of the diagnostic translations info #1711

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
a9f71b0
some room to breathe
tshepang Jun 30, 2023
07794cd
update location of .ftl files
tshepang Jun 30, 2023
54b877c
infor already provided earlier
tshepang Jun 30, 2023
016d099
remove stale info
tshepang Jun 30, 2023
94d4b48
missing word
tshepang Jun 30, 2023
b6aab59
translations will not be included in the codebase
tshepang Jun 30, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
79 changes: 19 additions & 60 deletions src/diagnostics/translation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
# Translation

rustc's diagnostic infrastructure supports translatable diagnostics using
[Fluent].

## Writing translatable diagnostics

There are two ways of writing translatable diagnostics:

1. For simple diagnostics, using a diagnostic (or subdiagnostic) derive
Expand All @@ -13,12 +15,17 @@ There are two ways of writing translatable diagnostics:
2. Using typed identifiers with `DiagnosticBuilder` APIs (in
`Diagnostic` implementations).

When adding or changing a translatable diagnostic, you don't need to worry
about the translations, only updating the original English message. Currently,
When adding or changing a translatable diagnostic,
you don't need to worry about the translations.
Only updating the original English message is required.
Currently,
each crate which defines translatable diagnostics has its own Fluent resource,
such as `parser.ftl` or `typeck.ftl`.
which is a file named `messages.ftl`,
located in the root of the crate
(such as`compiler/rustc_expand/messages.ftl`).

## Fluent

Fluent is built around the idea of "asymmetric localization", which aims to
decouple the expressiveness of translations from the grammar of the source
language (English in rustc's case). Prior to translation, rustc's diagnostics
Expand Down Expand Up @@ -68,13 +75,15 @@ You can consult the [Fluent] documentation for other usage examples of Fluent
and its syntax.

### Guideline for message naming

Usually, fluent uses `-` for separating words inside a message name. However,
`_` is accepted by fluent as well. As `_` fits Rust's use cases better, due to
the identifiers on the Rust side using `_` as well, inside rustc, `-` is not
allowed for separating words, and instead `_` is recommended. The only exception
is for leading `-`s, for message names like `-passes_see_issue`.

### Guidelines for writing translatable messages

For a message to be translatable into different languages, all of the
information required by any language must be provided to the diagnostic as an
argument (not just the information required in the English message).
Expand All @@ -86,10 +95,6 @@ excellent examples of translating messages into different locales and the
information that needs to be provided by the code to do so.

### Compile-time validation and typed identifiers
Currently, each crate which defines translatable diagnostics has its own
Fluent resource in a file named `messages.ftl`, such as
[`compiler/rustc_borrowck/messages.ftl`] and
[`compiler/rustc_parse/messages.ftl`].

rustc's `fluent_messages` macro performs compile-time validation of Fluent
resources and generates code to make it easier to refer to Fluent messages in
Expand All @@ -100,60 +105,13 @@ from Fluent resources while building the compiler, preventing invalid Fluent
resources from causing panics in the compiler. Compile-time validation also
emits an error if multiple Fluent messages have the same identifier.

In `rustc_error_messages`, `fluent_messages` also generates a constant for each
Fluent message which can be used to refer to messages when emitting
diagnostics and guarantee that the message exists.

```rust
fluent_messages! {
typeck => "../locales/en-US/typeck.ftl",
}
```

For example, given the following Fluent...

```fluent
typeck_field_multiply_specified_in_initializer =
field `{$ident}` specified more than once
.label = used more than once
.label_previous_use = first use of `{$ident}`
```

...then the `fluent_messages` macro will generate:

```rust
pub static DEFAULT_LOCALE_RESOURCES: &'static [&'static str] = &[
include_str!("../locales/en-US/typeck.ftl"),
];

mod fluent_generated {
pub const typeck_field_multiply_specified_in_initializer: DiagnosticMessage =
DiagnosticMessage::new("typeck_field_multiply_specified_in_initializer");
pub const label: SubdiagnosticMessage =
SubdiagnosticMessage::attr("label");
pub const label_previous_use: SubdiagnosticMessage =
SubdiagnosticMessage::attr("previous_use_label");
}
```

`rustc_error_messages::fluent_generated` is re-exported and primarily used as
`rustc_errors::fluent`.

```rust
use rustc_errors::fluent;
let mut err = sess.struct_span_err(span, fluent::typeck_field_multiply_specified_in_initializer);
err.span_label(span, fluent::label);
err.span_label(previous_use_span, fluent::previous_use_label);
err.emit();
```

When emitting a diagnostic, these constants can be used like shown above.

## Internals

Various parts of rustc's diagnostic internals are modified in order to support
translation.

### Messages

All of rustc's traditional diagnostic APIs (e.g. `struct_span_err` or `note`)
take any message that can be converted into a `DiagnosticMessage` (or
`SubdiagnosticMessage`).
Expand Down Expand Up @@ -182,6 +140,7 @@ non-translatable diagnostics - this keeps all existing diagnostic calls
working.

### Arguments

Additional context for Fluent messages which are interpolated into message
contents needs to be provided to translatable diagnostics.

Expand All @@ -191,13 +150,14 @@ additional context to a diagnostic.
Arguments have both a name (e.g. "what" in the earlier example) and a value.
Argument values are represented using the `DiagnosticArgValue` type, which is
just a string or a number. rustc types can implement `IntoDiagnosticArg` with
conversion into a string or a number, common types like `Ty<'tcx>` already
conversion into a string or a number, and common types like `Ty<'tcx>` already
have such implementations.

`set_arg` calls are handled transparently by diagnostic derives but need to be
added manually when using diagnostic builder APIs.

### Loading

rustc makes a distinction between the "fallback bundle" for `en-US` that is used
by default and when another locale is missing a message; and the primary fluent
bundle which is requested by the user.
Expand All @@ -222,9 +182,8 @@ returned by `Emitter::fluent_bundle`. This bundle is used preferentially when
translating messages, the fallback bundle is only used if the primary bundle is
missing a message or not provided.

As of <!-- date-check --> Jan 2023, there are no locale bundles
distributed with the compiler, but mechanisms are implemented for loading
bundles.
There are no locale bundles distributed with the compiler,
but mechanisms are implemented for loading them.

- `-Ztranslate-additional-ftl` can be used to load a specific resource as the
primary bundle for testing purposes.
Expand Down