Add basic i18n guidance for `Display` #121065

CAD97 · 2024-02-14T03:37:42Z

I've tried to be relatively noncommittal here. The part I think is most important is to mention the concept of "display adapters" somewhere in the std::fmt documentation that has some chance of being discovered when people go looking for ways to provide context when Displaying their type.

Rendered:

Internationalization

Because a type can only have one Display implementation, it is often preferable to only implement Display when there is a single most "obvious" way that values can be formatted as text. This could mean formatting according to the "invariant" culture and "undefined" locale, or it could mean that the type display is designed for a specific culture/locale, such as developer logs.

If not all values have a justifiably canonical textual format or if you want to support alternative formats not covered by the standard set of possible formatting traits, the most flexible approach is display adapters: methods like str::escape_default or Path::display which create a wrapper implementing Display to output the specific display format.

The module docs do already have a localization header, so maybe this header should be l10n instead of i18n, or maybe this information should live under that header? I'm not sure, but here on the Display trait at least isn't a bad spot to put it.

The other side of this that comes up a lot is FromStr compatibility, but that's for a different PR.

rustbot · 2024-02-14T03:37:50Z

r? @cuviper

rustbot has assigned @cuviper.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

CAD97 · 2024-02-14T04:13:53Z

... that's what I get for doing the edit through the web UI. I'll squash the tidy commits tomorrow hopefully.

library/core/src/fmt/mod.rs

cuviper · 2024-03-05T00:52:57Z

I'll squash the tidy commits tomorrow hopefully.

Still planning to squash? Apart from that, r=me.

CAD97 · 2024-03-05T00:55:27Z

Doing so right now, actually, you happened to come around right when I did 🙂

Co-authored-by: Simon Farnsworth <[email protected]>

CAD97 · 2024-03-05T01:07:29Z

Squashed, and tidy didn't get mad. Don't recall if I've been whitelisted but might as well try:

@bors r=cuviper rollup=always

bors · 2024-03-05T01:07:32Z

@CAD97: 🔑 Insufficient privileges: Not in reviewers

bors · 2024-03-05T01:07:33Z

@CAD97: 🔑 Insufficient privileges: not in try users

cuviper · 2024-03-05T01:08:52Z

@bors r+ rollup=always

bors · 2024-03-05T01:08:54Z

📌 Commit 215a4b6 has been approved by cuviper

It is now in the queue for this repository.

Add basic i18n guidance for `Display` I've tried to be relatively noncommittal here. The part I think is most important is to mention the concept of "display adapters" *somewhere* in the `std::fmt` documentation that has some chance of being discovered when people go looking for ways to provide context when `Display`ing their type. Rendered: > ### Internationalization > > Because a type can only have one `Display` implementation, it is often preferable to only implement `Display` when there is a single most "obvious" way that values can be formatted as text. This could mean formatting according to the "invariant" culture and "undefined" locale, or it could mean that the type display is designed for a specific culture/locale, such as developer logs. > > If not all values have a justifiably canonical textual format or if you want to support alternative formats not covered by the standard set of possible [formatting traits], the most flexible approach is display adapters: methods like [`str::escape_default`] or [`Path::display`] which create a wrapper implementing `Display` to output the specific display format. > > [formatting traits]: https://doc.rust-lang.org/nightly/std/fmt/index.html#formatting-traits > [`str::escape_default`]: https://doc.rust-lang.org/nightly/std/primitive.str.html#method.escape_default > [`Path::display`]: https://doc.rust-lang.org/nightly/std/path/struct.Path.html#method.display The module docs do already have a [localization header](https://doc.rust-lang.org/nightly/std/fmt/index.html#localization), so maybe this header should be l10n instead of i18n, or maybe this information should live under that header? I'm not sure, but here on the `Display` trait at least isn't a *bad* spot to put it. The other side of this that comes up a lot is `FromStr` compatibility, but that's for a different PR.

Rollup of 15 pull requests Successful merges: - rust-lang#121065 (Add basic i18n guidance for `Display`) - rust-lang#121202 (Limit the number of names and values in check-cfg diagnostics) - rust-lang#121213 (Add an example to demonstrate how Rc::into_inner works) - rust-lang#121262 (Add vector time complexity) - rust-lang#121287 (Clarify/add `must_use` message for Rc/Arc/Weak::into_raw.) - rust-lang#121664 (Adjust error `yield`/`await` lowering) - rust-lang#121838 (Use the correct logic for nested impl trait in assoc types) - rust-lang#121860 (Add a tidy check that checks whether the fluent slugs only appear once) - rust-lang#121913 (Don't panic when waiting on poisoned queries) - rust-lang#121959 (Removing absolute path in proc-macro) - rust-lang#121975 (hir_analysis: enums return `None` in `find_field`) - rust-lang#121978 (Fix duplicated path in the "not found dylib" error) - rust-lang#121987 (pattern analysis: abort on arity mismatch) - rust-lang#121993 (Avoid using unnecessary queries when printing the query stack in panics) - rust-lang#121997 (interpret/cast: make more matches on FloatTy properly exhaustive) r? `@ghost` `@rustbot` modify labels: rollup

Add basic i18n guidance for `Display` I've tried to be relatively noncommittal here. The part I think is most important is to mention the concept of "display adapters" *somewhere* in the `std::fmt` documentation that has some chance of being discovered when people go looking for ways to provide context when `Display`ing their type. Rendered: > ### Internationalization > > Because a type can only have one `Display` implementation, it is often preferable to only implement `Display` when there is a single most "obvious" way that values can be formatted as text. This could mean formatting according to the "invariant" culture and "undefined" locale, or it could mean that the type display is designed for a specific culture/locale, such as developer logs. > > If not all values have a justifiably canonical textual format or if you want to support alternative formats not covered by the standard set of possible [formatting traits], the most flexible approach is display adapters: methods like [`str::escape_default`] or [`Path::display`] which create a wrapper implementing `Display` to output the specific display format. > > [formatting traits]: https://doc.rust-lang.org/nightly/std/fmt/index.html#formatting-traits > [`str::escape_default`]: https://doc.rust-lang.org/nightly/std/primitive.str.html#method.escape_default > [`Path::display`]: https://doc.rust-lang.org/nightly/std/path/struct.Path.html#method.display The module docs do already have a [localization header](https://doc.rust-lang.org/nightly/std/fmt/index.html#localization), so maybe this header should be l10n instead of i18n, or maybe this information should live under that header? I'm not sure, but here on the `Display` trait at least isn't a *bad* spot to put it. The other side of this that comes up a lot is `FromStr` compatibility, but that's for a different PR.

…iaskrgr Rollup of 9 pull requests Successful merges: - rust-lang#121065 (Add basic i18n guidance for `Display`) - rust-lang#121301 (errors: share `SilentEmitter` between rustc and rustfmt) - rust-lang#121744 (Stop using Bubble in coherence and instead emulate it with an intercrate check) - rust-lang#121829 (Dummy tweaks (attempt 2)) - rust-lang#121857 (Implement async closure signature deduction) - rust-lang#121894 (const_eval_select: make it safe but be careful with what we expose on stable for now) - rust-lang#121905 (Add a `description` field to target definitions) - rust-lang#122022 (loongarch: add frecipe and relax target feature) - rust-lang#122028 (Remove some dead code) r? `@ghost` `@rustbot` modify labels: rollup

Add basic i18n guidance for `Display` I've tried to be relatively noncommittal here. The part I think is most important is to mention the concept of "display adapters" *somewhere* in the `std::fmt` documentation that has some chance of being discovered when people go looking for ways to provide context when `Display`ing their type. Rendered: > ### Internationalization > > Because a type can only have one `Display` implementation, it is often preferable to only implement `Display` when there is a single most "obvious" way that values can be formatted as text. This could mean formatting according to the "invariant" culture and "undefined" locale, or it could mean that the type display is designed for a specific culture/locale, such as developer logs. > > If not all values have a justifiably canonical textual format or if you want to support alternative formats not covered by the standard set of possible [formatting traits], the most flexible approach is display adapters: methods like [`str::escape_default`] or [`Path::display`] which create a wrapper implementing `Display` to output the specific display format. > > [formatting traits]: https://doc.rust-lang.org/nightly/std/fmt/index.html#formatting-traits > [`str::escape_default`]: https://doc.rust-lang.org/nightly/std/primitive.str.html#method.escape_default > [`Path::display`]: https://doc.rust-lang.org/nightly/std/path/struct.Path.html#method.display The module docs do already have a [localization header](https://doc.rust-lang.org/nightly/std/fmt/index.html#localization), so maybe this header should be l10n instead of i18n, or maybe this information should live under that header? I'm not sure, but here on the `Display` trait at least isn't a *bad* spot to put it. The other side of this that comes up a lot is `FromStr` compatibility, but that's for a different PR.

…iaskrgr Rollup of 10 pull requests Successful merges: - rust-lang#121065 (Add basic i18n guidance for `Display`) - rust-lang#121744 (Stop using Bubble in coherence and instead emulate it with an intercrate check) - rust-lang#121829 (Dummy tweaks (attempt 2)) - rust-lang#121832 (Add new Tier-3 target: `loongarch64-unknown-linux-musl`) - rust-lang#121857 (Implement async closure signature deduction) - rust-lang#121894 (const_eval_select: make it safe but be careful with what we expose on stable for now) - rust-lang#122014 (Change some attributes to only_local.) - rust-lang#122016 (will_wake tests fail on Miri and that is expected) - rust-lang#122018 (only set noalias on Box with the global allocator) - rust-lang#122028 (Remove some dead code) r? `@ghost` `@rustbot` modify labels: rollup

…iaskrgr Rollup of 9 pull requests Successful merges: - rust-lang#121065 (Add basic i18n guidance for `Display`) - rust-lang#121744 (Stop using Bubble in coherence and instead emulate it with an intercrate check) - rust-lang#121829 (Dummy tweaks (attempt 2)) - rust-lang#121857 (Implement async closure signature deduction) - rust-lang#121894 (const_eval_select: make it safe but be careful with what we expose on stable for now) - rust-lang#122014 (Change some attributes to only_local.) - rust-lang#122016 (will_wake tests fail on Miri and that is expected) - rust-lang#122018 (only set noalias on Box with the global allocator) - rust-lang#122028 (Remove some dead code) r? `@ghost` `@rustbot` modify labels: rollup

Rollup merge of rust-lang#121065 - CAD97:display-i18n, r=cuviper Add basic i18n guidance for `Display` I've tried to be relatively noncommittal here. The part I think is most important is to mention the concept of "display adapters" *somewhere* in the `std::fmt` documentation that has some chance of being discovered when people go looking for ways to provide context when `Display`ing their type. Rendered: > ### Internationalization > > Because a type can only have one `Display` implementation, it is often preferable to only implement `Display` when there is a single most "obvious" way that values can be formatted as text. This could mean formatting according to the "invariant" culture and "undefined" locale, or it could mean that the type display is designed for a specific culture/locale, such as developer logs. > > If not all values have a justifiably canonical textual format or if you want to support alternative formats not covered by the standard set of possible [formatting traits], the most flexible approach is display adapters: methods like [`str::escape_default`] or [`Path::display`] which create a wrapper implementing `Display` to output the specific display format. > > [formatting traits]: https://doc.rust-lang.org/nightly/std/fmt/index.html#formatting-traits > [`str::escape_default`]: https://doc.rust-lang.org/nightly/std/primitive.str.html#method.escape_default > [`Path::display`]: https://doc.rust-lang.org/nightly/std/path/struct.Path.html#method.display The module docs do already have a [localization header](https://doc.rust-lang.org/nightly/std/fmt/index.html#localization), so maybe this header should be l10n instead of i18n, or maybe this information should live under that header? I'm not sure, but here on the `Display` trait at least isn't a *bad* spot to put it. The other side of this that comes up a lot is `FromStr` compatibility, but that's for a different PR.

rustbot assigned cuviper Feb 14, 2024

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-libs Relevant to the library team, which will review and decide on the PR/issue. labels Feb 14, 2024

This comment has been minimized.

Sign in to view

mathstuf reviewed Feb 19, 2024

View reviewed changes

library/core/src/fmt/mod.rs Outdated Show resolved Hide resolved

farnz reviewed Feb 20, 2024

View reviewed changes

library/core/src/fmt/mod.rs Outdated Show resolved Hide resolved

CAD97 and others added 2 commits March 4, 2024 19:58

Explain use of display adapters

4dbd256

doc wording improvements

215a4b6

Co-authored-by: Simon Farnsworth <[email protected]>

CAD97 force-pushed the display-i18n branch from 653ddd6 to 215a4b6 Compare March 5, 2024 00:59

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Mar 5, 2024

jhpratt mentioned this pull request Mar 5, 2024

Rollup of 15 pull requests #122008

Closed

matthiaskrgr mentioned this pull request Mar 5, 2024

Rollup of 10 pull requests #122030

Closed

matthiaskrgr mentioned this pull request Mar 5, 2024

Rollup of 9 pull requests #122032

Closed

matthiaskrgr mentioned this pull request Mar 5, 2024

Rollup of 9 pull requests #122033

Closed

matthiaskrgr mentioned this pull request Mar 5, 2024

Rollup of 10 pull requests #122039

Closed

matthiaskrgr mentioned this pull request Mar 5, 2024

Rollup of 9 pull requests #122045

Merged

bors merged commit 49ff95d into rust-lang:master Mar 6, 2024
11 checks passed

rustbot added this to the 1.78.0 milestone Mar 6, 2024

CAD97 deleted the display-i18n branch March 6, 2024 04:51

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add basic i18n guidance for `Display` #121065

Add basic i18n guidance for `Display` #121065

CAD97 commented Feb 14, 2024 •

edited

Loading

rustbot commented Feb 14, 2024

This comment has been minimized.

This comment has been minimized.

CAD97 commented Feb 14, 2024

cuviper commented Mar 5, 2024

CAD97 commented Mar 5, 2024

CAD97 commented Mar 5, 2024

bors commented Mar 5, 2024

bors commented Mar 5, 2024

cuviper commented Mar 5, 2024

bors commented Mar 5, 2024

Add basic i18n guidance for Display #121065

Add basic i18n guidance for Display #121065

Conversation

CAD97 commented Feb 14, 2024 • edited Loading

Internationalization

rustbot commented Feb 14, 2024

This comment has been minimized.

This comment has been minimized.

CAD97 commented Feb 14, 2024

cuviper commented Mar 5, 2024

CAD97 commented Mar 5, 2024

CAD97 commented Mar 5, 2024

bors commented Mar 5, 2024

bors commented Mar 5, 2024

cuviper commented Mar 5, 2024

bors commented Mar 5, 2024

Add basic i18n guidance for `Display` #121065

Add basic i18n guidance for `Display` #121065

CAD97 commented Feb 14, 2024 •

edited

Loading