search

projectfluent / fluent-rs

Rust implementation of Project Fluent
https://projectfluent.org
Apache License 2.0
1.08k stars 97 forks source link

Fluent is not approachable for a beginner #180

Open teohhanhui opened 4 years ago

teohhanhui commented 4 years ago

I cannot find an example putting everything together for a practical implementation. There are 3 disparate examples:

  1. fluent-bundle/examples/simple-app.rs
  2. fluent-fallback/examples/simple-fallback.rs
  3. fluent-resmgr/examples/simple-resmgr.rs

Is it expected that we use all of fluent_bundle, fluent_langneg, fluent_fallback and fluent_resmgr together? If so, there should be an example showing how all the pieces fit together. If not, there should be explanation of when to use what (and why not).

teohhanhui commented 4 years ago

Of course, there's also the problem that all these "simple" examples are anything but simple. But I realize that's something that's being worked on.

Perhaps the goal could be to have a chapter on l10n in the Rust Book?

zbraniecki commented 4 years ago

Hi. Thank you for the feedback.

Is it expected that we use all of fluent_bundle, fluent_langneg, fluent_fallback and fluent_resmgr together?

Yes. Although you can replace any part - you can provide different language negotiation, different fallbacking and different resource management. Those are just examples.

If so, there should be an example showing how all the pieces fit together. If not, there should be explanation of when to use what (and why not).

I intend to add it once I stablize the higher level APIs a bit more.

Of course, there's also the problem that all these "simple" examples are anything but simple. But I realize that's something that's being worked on.

Good localization system is not easy unfortunately. We're focused on lower level APIs now, and I'm planning to start working on higher level APIs soon.

For now, I recommend looking at https://crates.io/crates/fluent-templates and https://crates.io/crates/fluent-ergonomics

I hope to get to the level of simplicity that the current JS fluent-dom and fluent-react have. It'll take a bit :)

RedMser commented 5 months ago

Hey! As someone who just tried Fluent for the first time via the Rust bindings, my experience was very similar to OP's and I'm very glad I found this issue to help pointing me in a starting direction at all. Without this, I would've likely not figured out what to do and how to get it working.

For anyone who wants to tackle this, I think the fluent-ergonomics crate was my best way for "getting started", although sadly the source code is no longer on GitHub (you can still download it via crates.io) and it uses a slightly outdated API. Having a similar code as a "hello world" sample on the repository's main readme might help? Just a "load ftl file" and a "translate message" method.

I was also a bit confused about which packages I need to install, so maybe adding a sentence to the readme along the lines of "to use fluent in your app, you only need to have the fluent crate installed. The rest are only for digging into internals and using parts of the whole."