search

google / rust_icu

rust_icu: rust bindings for ICU (International Components for Unicode) library
Apache License 2.0
117 stars 28 forks source link

Doc request? #196

Open EvanCarroll opened 3 years ago

EvanCarroll commented 3 years ago

I'm not even sure what I'm reading.. Is this not made for users at all because it's low level?

Where is the simple "hello world" example, with instructions on how to get to/from xliff? This crate is the first thing that comes up when you search for icu messageformat rust.

filmil commented 3 years ago

I'm not even sure what I'm reading.. Is this not made for users at all because it's low level?

Hello @EvanCarroll, I agree that documentation could be better.

Since rust_icu is really a wrapper on top of ICU4C, we're kind of piggybacking off the documentation available there. Sadly, while in theory we'd be able to take the API documentation over from ICU4C, in practice rustdoc gets confused about inline C++ code examples, so we had to turn documentation transfer off. This makes the documentation situation a bit worse than it otherwise would have been. Sorry about that.

The canonical place for rustdocs is at https://docs.rs/crate/rust_icu/ and the repo here is open for contributions. The reality is that you may end up being a trailblazer, in which case a PR that documents the things you learned along the way would be most welcome.

Where is the simple "hello world" example, with instructions on how to get to/from xliff? This crate is the first thing that comes up when you search for icu messageformat rust.

ICU doesn't really deal with L10N interchange formats, so it doesn't really have an answer for what to do with or how to maintain XLIFF files. Decisions on how I18N-ize your code, or bundle L10N resources and load them for use is out of its scope, and hence it is out of the scope of rust_icu too. You will see the same thing at the official ICU docs: https://unicode-org.github.io/icu/userguide/format_parse/messages/ While they explain how message formatting works, there is no word about interchange formats.

What ICU does provide for you in this workflow is the message formatter, which you can think of as a glorified locale-sensitive printf.

Could you be a bit more specific what you are trying to achieve? Perhaps that way we can work out together how you can get there despite the obvious deficiencies of rust_icu docs.