maximilien/i18n4go

Documentation suggestion

Closed this issue · 1 comments

robfig commented

Really cool project!

If I understand correctly, the workflow is to write your Go code as usual, process it with this command line tool which rewrites it to insert T() calls and extract messages, and then build the rewritten files?

Just a suggestion: it would be helpful to have the high level workflow in the documentation overview, since it's not a usual sort of thing

maximilien commented

@robfig,

Sorry it took so long to reply. Yep indeed. We need a blog post or two on how to use the tool and the basic recommended flow. The main flow is close to what you suggest but not quite. To help you out now, read on.

The recommended flow is to use the commands in the following order:

  1. extract-strings which will automatically extract every string from your Go source files and create a JSON and optionally a PO file. For each command, use the help or README.md for details and to experiment for your project.
  2. merge-strings to create one file and removing what is not needed and strings you do not want to i18n. This could be important and time consuming but to help this process, we've found that it's good to keep a list of all the strings that you do not want to i18n as well as string patterns (as regex). Take a look at the CF CLI excluded.json for a real world example file you might end up with. The regex in there might be useful to reuse.
  3. might need to do 1 again, but using excluded.json. The outcome should not be the file or files for en_US for all the strings that will be i18n for your app. So for instance: en_US.all.json
  4. rewrite-package using the file or files in 3. This will rewrite your code to use the T() function and also deal with parameters, though using the pattern: Arg0, Arg1, etc. NOTE that this step will rewrite (yes, modify) your code. You can always go fmt so the code will look fine. All files that contain strings that need to be i18n will be rewritten.
  5. create-translations to create initial translation file or files for each language you want to support.
    For instance will create fr_FR for French and every other locale_Language you specify. This could be done manually. The reason to use tool is optional next step and also because helps streamline your build process...
  6. [optional] create-translations with Google Translate API. You will need to have a Google Translate API key (NOTE: might require you to pay or at least enter your credit card). Generally the strings generated by Google Translate are OK not great. They usually require additional work, however, we have found that they can be a great start to send to translation team(s).
  7. verify-strings this will help you ensure that your translation files, e.g., en_US.all.json and fr_FR.all.json, and others, all have the same keys. This is important since if you are missing a key then for that language you might crash your app. We recommend using this during your build and CI and not build resulting app in 8 if this step fails.
  8. package your app with your i18n resource files. The packaging is slightly tricky since one of the great value of Golang is to have one binary file distribution for your app. This means you need to convert your i18n resource files (the JSON files) into binary that can be loaded in code (as code). We've been using go-bindata for the CF CLI and that seems to work pretty well. See this script on how we used it in the CF CLI. Other alternatives exist but we have not tried them.
  9. ship and profit 🍻

I have a working blog post or two that I started in the docs directory with the intent of documenting these steps with an example app, but never got to finish. Cannot promise when but it will be done.

In the mean time, let me know if you have questions.

Best,

dr.max