search

lingui / js-lingui

🌍 📖 A readable, automated, and optimized (3 kb) internationalization for JavaScript
https://lingui.dev
MIT License
4.54k stars 380 forks source link

Improve documentation how to work with message catalogs #392

Closed axhamre closed 5 years ago

axhamre commented 5 years ago

I wanted to give this project a shot, because on the surface things looked promising. But struggling with it for a couple of hours I honestly wonder why so complicated?

I apologize for the negativity, please only refer to this as some constructive feedback from someone that truly gave the package a fair chance 🙏

  1. Confusion CLI vs yarn/npm commands. The guides instruct you to insert script commands in package.json but then instruct you to use the CLI versions.
  2. It's really not clear what the point is with the commands extract and compile. I've used the library react-i18next and things ran smoothly without having to run commands. I could see one single point of this - and that's if the translation tags and translated strings where kept in sync, i.e. if I rename or delete a tag that it would sync the structure in the json files. But no that didn't work.
  3. Loading of translations is not obvious. Why do I have to import those manually? I assume if implementing @lingui/loader successfully, the app is reloaded on every new <Trans> tag or changed translation? But you lost me there. There's one contrived example in the docs where we need to integrate a stateful component (nowhere seen elsewhere in the guides) and working with async/await. Does it have to be this difficult to set things up?
tricoder42 commented 5 years ago

  1. Originally I used global lingui command, but it's easier and safer to use local commands. There might be sections in docs which weren't updated correctly.

    If you've found such places, feel free to send a PR or list them here so I can fix them faster.

  2. Could you please elaborate on how it didn't work? It's exactly as you say: Messages should be extracted from source code automatically. Maintaining external catalog manually doesn't scale and there's lot of things which could go wrong (missing/obsolete messages, wrong message format, etc).

    compile prepares the catalog for production. Right now it compiles/minifies messages, so you don't need to use parser at runtime. It also validates that all messages are correct, so you don't get any runtime errors. In future there's gonna be lot more logic, e.g. resolution of fallback languages or minification of IDs (#139).

    The full reason is that messages are stored in file format, which is suitable for translators (PO, JSON, XLIFF), but in the code you should always load the simples format (JSON or JS module) to avoid additional runtime costs.

  3. Yeah, you have to import that manually. At the moment I don't know about any library which would automagically load translations for you. You always have to specify the source, one way or another.

    @lingui/loader only handles on-the-fly compilation of messages, so you don't have to run lingui compile manually. The example in docs is indeed too verbose, because when I wrote the lib initially I focused on stuff which I missed in other libs. Component loading messages for ~100 lines of code and it was specific to my project, so I just document it and let users to implement their own solutions depending on their stack.

    Next version's gonna be much easier, because the message loading is moved to core. There're already examples in next branch.

axhamre commented 5 years ago

  1. At bullet number 4 in the installation guide we're instructed to "Add following scripts to your package.json". But in the React guide we're told to use lingui ...:

  2. E.g. I started out having the contents of a Trans tag to be Surveys. When later changing to home.surveyTitleTrans>, and running both extract and compile - both the first and second elements are in the json file. The former with the value obsolete: true, which indicates that it's obsolete, but IMO it shouldn't be there at all if has been removed.

tricoder42 commented 5 years ago

  1. Fixed. All mentions of global installation are removed from docs.

  2. No, actually this is supposed to work like that. Imagine you already have the message translated. If you change the message ID and the former message is removed, you lost the translation. Now it's marked as obsolete, so you can copy the translation manually and then run extract --clean to remove all obsolete messages.

    In future it would be great to detect changes of message IDs, but that's not trivial.