Analysis of `bevy_fluent` for upstreaming

[aecsocket]

Internationalization (i18n) is important but often overlooked in games, so it's important that Bevy does this right. A 3rd party crate for i18n already exists, bevy_fluent, and this issue describes my thoughts on the crate.

This writeup is done on version 0.8.0 of the crate.

Getting started

First thing to point out is the lack of documentation:

• descriptions of structs and modules are very brief
• readme lacks much depth
• no examples in the docs (there are some in examples/ though)

There's very little documentation right now on how to actually use the i18n features, so the best place to start is the examples. A slimmed-down version of the minimal example looks like:

use bevy_fluent::{Locale, FluentPlugin};
use unic_langid::langid; // !!!
use fluent_content::Content; // !!!
// use ...

fn main() {
    App::new()
        // ...
        .add_plugins(FluentPlugin)
        .insert_resource(Locale::new(langid!("en-US")))
        .add_systems(Startup, localized_hello_world)
        .run();
}

fn localized_hello_world(
    localization_builder: LocalizationBuilder,
    asset_server: Res<AssetServer>,
    mut handle: Local<Option<Handle<LoadedFolder>>>,
    mut localization: Local<Option<Localization>>,
) {
    let handle = &*handle.get_or_insert_with(|| asset_server.load_folder("locales"));
    if let Some(LoadState::Loaded) = asset_server.get_load_state(handle) {
        let localization = localization.get_or_insert_with(|| localization_builder.build(handle));

        info!("{}", localization.content("hello-world"));
    }
}

I experienced some friction with this initial, relatively simple example:

• With bevy_fluent alone, this example will not compile. I also needed to add unic_langid and fluent_content as dependencies to the crate.
  • fluent_content should probably be re-exported; unic_langid could be as well but I don't know. If it's in the public API then it should be, right?
• This might just be an issue with Bevy's assets ergonomics, but the localized_hello_world system also does a bunch of stuff relating to loading the i18n assets. This adds a ton of noise to the code for what should be a relatively simple example.
  • The Localization derives Resource, so an example showing how you can just add Res<Localization> would be useful here
• There seems to be no way to add arguments to the content call, which is however supported in fluent::FluentBundle as well as the fluent::fluent_args! macro. Imo it's very important to have an easy-to-use and frictionless formatting mechanism with arguments here. However I like the relative simplicity of localization.content("message-key") here.

In general, I like the approach of having a single Locale resource, and using a Localization to store the actual translation content, since this feels like a standard approach that an app would use:

fn localized_hello_world(i18n: Res<Localization>) {
    info!("{:?}", i18n.content("hello-world"));
}

Architecture

Quickly reading through the source I like the general architecture, it's fairly simple and the module names are self-descriptive (but again, more docs would be very useful).

I'm not a fan of some of the naming like BundleAsset, as this is vague in meaning (the name doesn't relate to i18n in any way) and conflicts with Bevy's existing Bundle terminology (i.e. a bundle of components). In a fully qualified name like bevy_fluent::BundleAsset it makes more sense, but if this were to be upstreamed, it should probably be renamed to make its purpose as an i18n tool clear.

The "fallback chain" mechanism is somewhat unclear - it's not immediately obvious where this is configured, and how it works exactly.

The crate seems to be coupled tightly to folders - I honestly don't know if this is a good idea or not. It limits flexibility, but then again most people will be loading translations from folders.

Overall, I think the crate is in a pretty good state. My priority for this would be:

• docs
• clean up the examples and add comments to them to make it explicitly clear what's going on, and why things are done this way (i.e. what does the Locale resource do?)
• making the process of integrating i18n as frictionless as possible for devs - if there's a lot of annoyances involved in translating strings, then devs simply won't do it
  • this includes making setup of i18n super simple, using i18n in systems, and passing arguments into messages

[alice-i-cecile]

[4:11 PM]TIMMÄH: I think there are multiple separate parts to this: Locale management, i.e. to select the current locale and handle fallbacks (easy) General asset localization, i.e., being able to provide localized components for any asset file. We should be able to localize images/textures, videos, audio, etc) Text localization. This should likely use the foundations built by 2 and also provide Fluent integration, e.g. in the form of an asset loader and integrating licely with bevy_ui [4:11 PM]Boris: 2 sounds like the hardest to implement right now [4:11 PM]Boris: I can't think of a good way that you'd localize entire textures or videos in the engine [4:14 PM]TIMMÄH: For 2, I really want to experiment with setting up an asset source which can handle localized assets, so that you can just write something like asset_server.load("localized://your_image.png") and it will load your_image/en.png if english is selected as active locale. Unfortunately I don't have so much time right now to work on this and ran into some lifetime issues in an experiment. But I think this would give us the best UX: You still get hot reloading and all that stuff even when using localization and to localize your game all you have to do is to replace your asset by a folder with the localized versions and add localized:// to your load call

@TimJentzsch on Discord