github.com/kisunji/i18n4go@v0.2.7/README.md (about) 1 i18n Tooling for the Go Language [![Build Status](https://travis-ci.org/maximilien/i18n4go.svg?branch=master)](https://travis-ci.org/maximilien/i18n4go#) 2 ============================== 3 4 [![Join the chat at https://gitter.im/maximilien/i18n4go](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/maximilien/i18n4go?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) [![dWOpen Slack](https://raw.githubusercontent.com/maximilien/i18n4go/master/slack/slack.png)](https://dwopen.slack.com/messages/i18n4go/) 5 6 This is a general purpose internationalization (i18n) tooling for Go language (Golang) programs. It allows you to prepare Go language code for internationalization and localization (l10n). You can also use it to help maintain the resulting i18n-enabled Golang code so that it remains internationalized. This tool was extracted while we worked on enabling the [Cloud Foundry CLI](https://github.com/cloudfoundry/cli) with i18n support. 7 8 This tool is licensed under the [Apache 2.0 OSS license](https://github.com/maximilien/i18n4go/blob/master/LICENSE). We'd love to hear from you if you are using, attempting to use, or planning to use this tool. 9 10 Two additional ways, besides Gitter or Slack chat above, to contact us: 11 12 1. Feel free to [open an issue (good or bad)](https://github.com/maximilien/i18n4go/issues) here on Github. 13 2. Send email to `i18n4go` at the Gmail domain. 14 15 ## Getting Started 16 ------------------ 17 18 ### Overview Presentations, Talks, Blogs 19 ---------------------------------------- 20 21 * Talk at [GoSF Meetup](http://www.meetup.com/golangsf/events/220603955/) on April, 2015. Slides ([PDF](https://github.com/maximilien/presentations/blob/master/2015/i18n4go-gosf-meetup/releases/i18n4go-v0.4.1.pdf) and [PPTX](https://github.com/maximilien/presentations/blob/master/2015/i18n4go-gosf-meetup/releases/i18n4go-v0.4.1.pptx)), [demo](https://github.com/maximilien/i18n4go/tree/master/examples/demo1) 22 23 * Blog post on July, 2015 at IBM's developerWorks: [i18n4go: Taking your Golang Projects Global for Fun or Profits](https://developer.ibm.com/open/2015/07/18/i18n4go-taking-golang-projects-global-fun-profits/) 24 25 ### Getting Latest Executable: i18n4go 26 -------------------------------------- 27 28 Assuming you have a valid [Golang 1.4.2](https://golang.org/dl/) or [later](https://golang.org/dl/) installed for your system, you can quickly get the latest `i18n4go` executable by running the following `go` command: 29 30 ``` 31 $ go get github.com/maximilien/i18n4go/i18n4go 32 ``` 33 34 This will build and place the `i18n4go` executable built for your operating system in your `$GOPATH/bin` directory. 35 36 ### Cloning and Building 37 ------------------------ 38 39 Clone this repo and build it. Using the following commands on a Linux or Mac OS X system: 40 41 ``` 42 $ mkdir -p i18n4go/src/github.com/maximilien 43 $ export GOPATH=$(pwd)/i18n4go:$GOPATH 44 $ cd i18n4go/src/github.com/maximilien 45 $ git clone https://github.com/maximilien/i18n4go.git 46 $ cd i18n4go 47 $ ./bin/build 48 ``` 49 50 NOTE: if you get any dependency errors, then use `go get path/to/dependency` to get it, e.g., `go get github.com/onsi/ginkgo` and `go get github.com/onsi/gomega` 51 52 The executable output should now be located in: `out/i18n4go`. Place it wherever you want, e.g., `/usr/local/bin` on Linux or Mac OS X. 53 54 You can now use the `i18n4go` executable to issue some of the typical i18n tooling processes. 55 56 ### Running Tests 57 ----------------- 58 59 You should run the tests to make sure all is well, do this with: `$ ./bin/test` in your cloned repository. 60 61 The output should be similar to: 62 63 ``` 64 $ bin/test 65 66 Cleaning build artifacts... 67 68 Formatting packages... 69 70 Integration Testing packages: 71 ok github.com/maximilien/i18n4go/integration/checkup 1.571s 72 ok github.com/maximilien/i18n4go/integration/create_translations 1.542s 73 ok github.com/maximilien/i18n4go/integration/extract_strings 1.694s 74 ok github.com/maximilien/i18n4go/integration/fixup 1.657s 75 ok github.com/maximilien/i18n4go/integration/merge_strings 1.645s 76 ok github.com/maximilien/i18n4go/integration/rewrite_package 1.853s 77 ok github.com/maximilien/i18n4go/integration/show_missing_strings 1.590s 78 ? github.com/maximilien/i18n4go/integration/test_helpers [no test files] 79 ok github.com/maximilien/i18n4go/integration/verify_strings 1.701s 80 81 Vetting packages for potential issues... 82 83 SWEET SUITE SUCCESS 84 ``` 85 86 ### Typical Workflow 87 -------------------- 88 89 The recommended workflow is to use the commands (documented below) in the following order. For each command, use the command's help or this README for details and to experiment for your project. So the nine steps are: 90 91 1. **extract-strings** which will automatically extract every string from your Go source files and create a JSON and optionally a PO file. 92 93 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](https://github.com/cloudfoundry/cli/blob/master/cf/i18n/excluded.json) for a real world example file you might end up with. The regex in there might be useful to reuse. 94 95 3. might need to do 1 again, but using `excluded.json`. The outcome should be the file or files for `en_US` for all the strings that will be i18n for your app. So for instance, if you decide to combine all into one: `en_US.all.json` 96 97 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 to your strings, using the pattern: `Arg0`, `Arg1`, etc. *NOTE* that this step will rewrite (yes, modify) your code. You can always use `go fmt` so the code will look fine. All files that contain strings that need to be i18n will be rewritten. You can do this step one package at a time. 98 99 5. **create-translations** to create initial translation file or files for each language that you want to support. 100 For instance to create `fr_FR` file(s) 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 the tool may help streamline your build process... The resulting files can be sent to human translators to be officially completed. 101 102 6. [optional] **create-translations** with [Google Translate API](https://cloud.google.com/translate/docs). You will need to have a Google Translate API key (*NOTE*: might require you to pay or at least enter your credit card if usage is above some threshold). Generally the strings generated by Google Translate are OK, but not great. They usually require additional work, however, we have found that they can be a good start when sending files to be officially translated by human translator team(s). 103 104 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 for CI and not build resulting app in 8 (next step) if this step fails. 105 106 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 source code). We've been using [go-bindata](https://github.com/jteeuwen/go-bindata) for the CF CLI and that seems to work pretty well. See [this script](https://github.com/cloudfoundry/cli/blob/fa7bcb07cdb6c6960f0907022bcef83ec4363a47/bin/generate-language-resources) on how we used it in the CF CLI. Other alternatives exist but we have not tried them. 107 108 9. ship and profit :) 109 110 ### Typical Workflow Diagram 111 112 ![Typical i18n4go workflow diagram](https://github.com/maximilien/i18n4go/blob/master/docs/images/typical-workflow.png) 113 114 ### Help 115 -------- 116 117 Printing the usage help: `$ i18n4go -h` or `$ i18n4go --help` 118 119 ``` 120 usage: i18n4go -c extract-strings [-vpe] [--dry-run] [--output-flat|--output-match-package|-o <outputDir>] -f <fileName> 121 or: i18n4go -c extract-strings [-vpe] [--dry-run] [--output-flat|--output-match-package|-o <outputDir>] -d <dirName> [-r] [--ignore-regexp <fileNameRegexp>] 122 123 usage: i18n4go -c rewrite-package [-v] [-r] -d <dirName> [--i18n-strings-filename <fileName> | --i18n-strings-dirname <dirName>] 124 or: i18n4go -c rewrite-package [-v] [-r] -f <fileName> --i18n-strings-filename <fileName> 125 126 usage: i18n4go -c merge-strings [-v] [-r] [--source-language <language>] -d <dirName> 127 128 usage: i18n4go -c verify-strings [-v] [--source-language <language>] -f <sourceFileName> --language-files <language files> 129 or: i18n4go -c verify-strings [-v] [--source-language <language>] -f <sourceFileName> --languages <lang1,lang2,...> 130 131 usage: i18n4go -c create-translations [-v] [--google-translate-api-key <api key>] [--source-language <language>] -f <fileName> --languages <lang1,lang2,...> -o <outputDir> 132 133 -h | --help prints the usage 134 -v verbose 135 ... 136 ``` 137 138 ## extract-strings 139 140 The general usage for `-c extract-strings` command is: 141 142 ``` 143 ... 144 EXTRACT-STRINGS: 145 146 -c extract-strings the extract strings command 147 148 -e [optional] the JSON file with strings to be excluded, defaults to excluded.json if present 149 -s [optional] the JSON file with regexp that specify a capturing group to be extracted instead of the full string matching the regexp 150 151 --po to generate standard .po files for translation 152 --meta [optional] create a *.extracted.json file with metadata such as: filename, directory, and positions of the strings in source file 153 --dry-run [optional] prevents any output files from being created 154 155 156 -o the output directory where the translation files will be placed 157 -f the go file name to extract strings 158 -d the directory containing the go files to extract strings 159 -r [optional] recursesively extract strings from all subdirectories 160 161 --output-flat generated files are created in the specified output directory (default) 162 --output-match-package generated files are created in directory to match the package name 163 164 --ignore-regexp [optional] a perl-style regular expression for files to ignore, e.g., ".*test.*" 165 166 ``` 167 168 The command `-c extract-strings` pulls strings out of go files. For the examples below we are running the tool on a copy of the the [CloudFoundry CLI](https://github.com/cloudfoundry/cli) cloned in the `./tmp` 169 170 ``` 171 $ i18n4go -c extract-strings -v --po -f ./tmp/cli/cf/app/app.go -o ./tmp/cli/i18n -output-match-package 172 173 i18n4go: extracting strings from file: ./tmp/cli/cf/app/app.go 174 Could not find: excluded.json 175 Loaded 0 excluded strings 176 Could not find: excluded.json 177 Loaded 0 excluded regexps 178 Extracted 10 strings from file: ./tmp/cli/cf/app/app.go 179 Saving extracted i18n strings to file: tmp/cli/i18n/app/app.go.en.json 180 Creating and saving i18n strings to .po file: ./tmp/cli/cf/app/app.go.en.po 181 Total time: 3.962ms 182 ``` 183 184 The output for the command above are three files, of which two are important for translation: 185 186 a. `./tmp/cli/i18n/app/app.go.en.json` 187 188 This file is the JSON formatted translation file for English. Some of its content is as follows: 189 190 ```json 191 [ 192 ... 193 { 194 "id": "Show help", 195 "translation": "Show help" 196 }, 197 { 198 "id": "%s help [COMMAND]", 199 "translation": "%s help [COMMAND]" 200 }, 201 ... 202 ] 203 ``` 204 205 b. Optionaly, using -p flag, it will generate `./tmp/cli/i18n/app/app.go.en.po` 206 207 This file is the [PO](https://www.gnu.org/software/gettext/manual/html_node/PO-Files.html) formatted translation file for English. Some of its content is as follows: 208 209 ``` 210 # filename: ../tmp/cli/cf/app/app.go, offset: 1617, line: 48, column: 16 211 msgid "Show help" 212 msgstr "Show help" 213 214 # filename: ../tmp/cli/cf/app/app.go, offset: 1657, line: 49, column: 28 215 msgid "%s help [COMMAND]" 216 msgstr "%s help [COMMAND]" 217 ... 218 ``` 219 220 To extract multiples files that are in one directory, use the following: 221 222 ``` 223 $ i18n4go -c extract-strings -v --po -d ./tmp/cli/cf/app/ -o ./tmp/cli/i18n -output-match-package -ignore-regexp ".*test.*" 224 225 ... 226 ``` 227 228 The generated output JSON files are in: `./tmp/cli/i18n/app` 229 230 ## merge-strings 231 232 The general usage for `-c merge-strings` command is: 233 234 ``` 235 ... 236 MERGE STRINGS: 237 238 -c merge-strings merges multiple <filename>.go.<language>.json files into a <language>.all.json 239 240 -d the directory containing the json files to combine 241 -r [optional] recursesively combine files from all subdirectories 242 243 --source-language [optional] the source language of the file, typically also part of the file name, e.g., "en_US" (default to 'en') 244 245 ``` 246 247 The command `-c merge-strings` combines strings in multiple `*.go.[lang].json` files generated by `Extract Strings` into one file. Using the same example source as above. 248 249 ``` 250 $ i18n4go -c merge-strings -v -d ./tmp/cli/i18n/app -source-language en 251 252 i18n4go: scanning file: tmp/cli/i18n/app/app.go.en.json 253 i18n4go: scanning file: tmp/cli/i18n/app/flag_helper.go.en.json 254 i18n4go: scanning file: tmp/cli/i18n/app/help.go.en.json 255 i18n4go: saving combined language file: tmp/cli/i18n/app/en.all.json 256 Total time: 1.283116ms 257 ``` 258 259 The output for the command above is one file placed in the same directory as the JSON files being merged: `en.all.json`. 260 This file containes one formatted translation for each translation generated by extract-strings for English. The `-source-language` flag 261 must match the language portion of the files in the directory, e.g., app.go.en.json, where the language is "en". 262 263 ## rewrite-package 264 265 The general usage for `-c rewrite-package` command is: 266 267 ``` 268 ... 269 REWRITE-PACKAGE: 270 271 -c rewrite-package the rewrite package command 272 273 -f the source go file to be rewritten 274 -d the directory containing the go files to rewrite 275 -o [optional] output diretory for rewritten file. If not specified, the original file will be overwritten 276 277 --i18n-strings-filename a JSON file with the strings that should be i18n enabled, typically the output of -extract-strings command 278 --i18n-strings-dirname a directory with the extracted JSON files, using -output-match-package with -extract-strings this directory should match the input files package name 279 --root-path the root path to the Go source files whose packages are being rewritten, defaults to working directory, if not specified 280 281 ``` 282 283 The command `-c rewrite-package` will modify the go source files such that every string identified in the JSON translation files are wrapped with the `T()` function. There are two cases: 284 285 a. running it on one source file 286 287 ``` 288 $ i18n4go -c rewrite-package -v -f tmp/cli/cf/app/help.go -i18n-strings-dirname tmp/cli/i18n/app/ -o tmp/cli/cf/app/ 289 290 i18n4go: rewriting strings for source file: tmp/cli/cf/app/help.go 291 i18n4go: adding init func to package: app to output dir: tmp/cli/cf/app 292 i18n4go: inserting T() calls for strings that need to be translated 293 saving file to path tmp/cli/cf/app/help.go 294 295 Total files parsed: 1 296 Total extracted strings: 17 297 Total time: 9.986963ms 298 ``` 299 300 b. running it on a directory 301 302 ``` 303 $ i18n4go -c rewrite-package -v -d tmp/cli/cf/app/ -i18n-strings-dirname tmp/cli/i18n/app/ -o tmp/cli/cf/app/ 304 305 i18n4go: rewriting strings in dir tmp/cli/cf/app/, recursive: false 306 307 i18n4go: loading JSON strings from file: tmp/cli/i18n/app/app.go.en.json 308 i18n4go: rewriting strings for source file: tmp/cli/cf/app/app.go 309 i18n4go: adding init func to package: app to output dir: tmp/cli/cf/app 310 i18n4go: inserting T() calls for strings that need to be translated 311 saving file to path tmp/cli/cf/app/app.go 312 i18n4go: loading JSON strings from file: tmp/cli/i18n/app/flag_helper.go.en.json 313 i18n4go: rewriting strings for source file: tmp/cli/cf/app/flag_helper.go 314 i18n4go: adding init func to package: app to output dir: tmp/cli/cf/app 315 i18n4go: inserting T() calls for strings that need to be translated 316 saving file to path tmp/cli/cf/app/flag_helper.go 317 i18n4go: loading JSON strings from file: tmp/cli/i18n/app/help.go.en.json 318 i18n4go: rewriting strings for source file: tmp/cli/cf/app/help.go 319 i18n4go: adding init func to package: app to output dir: tmp/cli/cf/app 320 i18n4go: inserting T() calls for strings that need to be translated 321 saving file to path tmp/cli/cf/app/help.go 322 323 Total files parsed: 3 324 Total extracted strings: 21 325 Total time: 16.648105ms 326 ``` 327 328 In both cases above the `-i18n-strings-dirname` specifies the directory containing the `<source.go>.en.json` file with the strings to process. 329 However, this can be replaced with `-i18n-strings-filename` and specify one JSON file (e.g., `en.all.json`) which contains all the strings. 330 331 --------- 332 333 The result in each case is that the source files are rewritten with the wrapped `T()` function but also dealing with converting interpolated strings into Go-style templated strings. For instance: 334 335 The following interpolated string: `"%s help [COMMAND]"` is templated to: `"{{.Arg0}} help [COMMAND]"` and rewritten automaticall as: 336 337 ``` 338 T("{{.Arg0}} help [COMMAND]", map[string]interface{}{"Arg0": cf.Name()}) 339 ``` 340 341 So in essence the strings in the JSON files that where interpolated become templated, that is new IDs for the default language. 342 343 ## create-translations 344 345 The general usage for `-c create-translations` command is: 346 347 ``` 348 ... 349 CREATE-TRANSLATIONS: 350 351 -c create-translations the create translations command 352 353 -f the source translation file 354 -o the output directory where the newly created translation files will be placed 355 356 --languages a comma separated list of valid languages with optional territory, e.g., \"en, en_US, fr_FR, es\" 357 --source-language [optional] the source language of the file, typically also part of the file name, e.g., \"en_US\" 358 --google-translate-api-key [optional] your public Google Translate API key which is used to generate translations (charge is applicable) 359 360 ``` 361 362 The command `-c create-translations` generates copies of the `-source-language` file, one per language specified in the `-languages` flag (seperated by comma). 363 364 ``` 365 $ i18n4go -c create-translations -v -f tmp/cli/i18n/app/en.all.json -source-language en -languages "en_US,fr_FR,es_ES,de_DE" -o tmp/cli/i18n/app/ 366 367 i18n4go: creating translation files for: tmp/cli/i18n/app/en.all.json 368 369 i18n4go: creating translation file copy for language: en_US 370 i18n4go: creating translation file: tmp/cli/i18n/app/en_US.all.json 371 i18n4go: created default translation file: tmp/cli/i18n/app/en_US.all.json 372 i18n4go: creating translation file copy for language: fr_FR 373 i18n4go: creating translation file: tmp/cli/i18n/app/fr_FR.all.json 374 i18n4go: created default translation file: tmp/cli/i18n/app/fr_FR.all.json 375 i18n4go: creating translation file copy for language: es_ES 376 i18n4go: creating translation file: tmp/cli/i18n/app/es_ES.all.json 377 i18n4go: created default translation file: tmp/cli/i18n/app/es_ES.all.json 378 i18n4go: creating translation file copy for language: de_DE 379 i18n4go: creating translation file: tmp/cli/i18n/app/de_DE.all.json 380 i18n4go: created default translation file: tmp/cli/i18n/app/de_DE.all.json 381 382 Total time: 2.143251ms 383 ``` 384 385 Optionally, we can create automated translations for the generated copies using Google Translate[link] passing the `google-translate-api-key` flag. 386 387 ## verify-strings 388 389 The general usage for `-c verify-strings` command is: 390 391 ``` 392 ... 393 VERIFY-STRINGS: 394 395 -c verify-strings the verify strings command 396 397 398 -f the source translation file 399 400 --source-language [optional] the source language of the source translation file (default to 'en') 401 --languages a comma separated list of valid languages with optional territory, e.g., "en, en_US, fr_FR, es" 402 --language-files a comma separated list of target files for different languages to compare, e.g., "en, en_US, fr_FR, es" 403 if not specified then the languages flag is used to find target files in same directory as source 404 405 ``` 406 407 The command `-c verify-strings` assures that combined language files have exactly the same keys. 408 409 For instance, in the example in `merge-strings` we created a combined language file called `./tmp/cli/i18n/app/en.all.json` and if we also 410 had a `./tmp/cli/i18n/app/fr.all.json` for French and that file had missing strings then running the `verify-strings` would generate a 411 `tmp/cli/i18n/app/fr.all.json.missing.diff.json`, as in the following: 412 413 ``` 414 $ i18n4go -c verify-strings -v -f tmp/cli/i18n/app/en.all.json -languages "fr" 415 416 targetFilenames: [tmp/cli/i18n/app/fr.all.json] 417 i18n4go: ERROR input file does not match target file: tmp/cli/i18n/app/fr.all.json 418 i18n4go: generated diff file: tmp/cli/i18n/app/fr.all.json.missing.diff.json 419 i18n4go: Error verifying target filename: tmp/cli/i18n/app/fr.all.json 420 i18n4go: Could not verify strings for input filename, err: i18n4go: target file is missing i18n strings with IDs: --,'%v',- 421 ``` 422 423 Similarly, `verify-strings` will make sure that no additonal strings are added. So if we had an additional German `de.all.json` file that included additional strings 424 running `verify-strings` would include a `tmp/cli/i18n/app/de.all.json.extra.diff.json`. 425 426 ``` 427 $ i18n4go -c -verify-strings -v -f tmp/cli/i18n/app/en.all.json -languages "fr,de" 428 429 targetFilenames: [tmp/cli/i18n/app/fr.all.json tmp/cli/i18n/app/de.all.json] 430 i18n4go: ERROR input file does not match target file: tmp/cli/i18n/app/fr.all.json 431 i18n4go: generated diff file: tmp/cli/i18n/app/fr.all.json.missing.diff.json 432 i18n4go: Error verifying target filename: tmp/cli/i18n/app/fr.all.json 433 i18n4go: WARNING target file has extra key with ID: advanced 434 i18n4go: WARNING target file has extra key with ID: apps 435 i18n4go: WARNING target file contains total of extra keys: 2 436 i18n4go: generated diff file: tmp/cli/i18n/app/de.all.json.extra.diff.json 437 i18n4go: Error verifying target filename: tmp/cli/i18n/app/de.all.json 438 i18n4go: Could not verify strings for input filename, err: i18n4go: target file has extra i18n strings with IDs: advanced,apps 439 ``` 440 441 Finally, if a combined language file contains both extra and missing keys then `verify-strings` will generate two diff files: `missing` and `extra`. 442 443 ## checkup 444 445 The general usage for `-c checkup` command is: 446 447 ``` 448 ... 449 CHECKUP: 450 451 -c checkup the checkup command 452 453 454 -q the qualifier to use when calling the T(...), defaults to empty but can be used to set to something like i18n for example, such that, i18n.T(...) is used for T(...) function 455 456 ``` 457 458 The `checkup` command ensures that the strings in code match strings in resource files and vice versa. 459 460 ## fixup 461 462 The general usage for `-c fixup` command is: 463 464 ``` 465 ... 466 FIXUP: 467 468 -c fixup the fixup command 469 ``` 470 471 The `fixup` command interactively lets users add, update, or remove translations keys from code and resource files. 472 473 ## Specifying `excluded.json` File 474 475 The exclude.json file can be used to manage which strings should not be extract with the `extracting-strings` command. In the `excluded.json` file, 476 you can specifie string literals to ignore as well as classes of strings using a Perl-style regular expression. We have provided an example file 477 [exclude](https://github.com/maximilien/i18n4go/blob/master/example/excluded.json) to demonstrate the string and regexp cases. 478 479 ### string literals 480 481 String literals are defined within the `excludedStrings` array. Any strings in your source files that exactly matches one of these will not be extracted 482 to the generated files from extracted strings. 483 484 ```json 485 ... 486 "excludedStrings" : [ 487 "", 488 " ", 489 "\n", 490 "help", 491 ... 492 ] 493 } 494 ``` 495 496 As an example run, generate an extracted string files useing the command: 497 498 ``` 499 $ i18n4go -c extract-strings -p -d ./tmp/cli/cf/app/ -o ./tmp/cli/i18n -output-match-package -ignore-regexp ".*test.*" -e ./example/excluded.json 500 ``` 501 502 If we inspect the `./tmp/cli/i18n/app/app.go.en.json` file there should not be an entry for `"id": "help"`, but you should still see an entry for `"id": "show help"` 503 504 ### regular expressions 505 506 Regular expressions can be defined using the same JSON annotation as string literals with the tag `"excludedRegexps"`. 507 508 ```json 509 { 510 ... 511 "excludedRegexps" : [ 512 "^\\w$", 513 "^json:" 514 ] 515 } 516 ``` 517 518 As an example for regular expressions, let us consider the `^json:`. This expression will remove any string containg `json:` which would be useful when parsing the 519 `./tmp/cli/cf/api/resources/events.go` file such as: `ExitDescription string `json:"exit_description"`. After running the command: 520 521 ``` 522 $ i18n4go -c extract-strings -v -d ./tmp/cli/cf/api/resources -o ./tmp/cli/i18n -output-match-package -ignore-regexp ".*test.*" -e ./example/excluded.json 523 ``` 524 525 We can inspect the `./tmp/cli/i18n/resources/events.go.en.json` file and see that there are no strings with the expression `json:`. 526 527 --------- 528 529 ## Troubleshooting / FAQs 530 ------------------------- 531 532 None for now. Submit questions/comments as issues and we will update here 533 534 ### Filing Bugs 535 --------------- 536 537 ##### For simple bugs (eg: text formatting, help messages, etc), please provide 538 539 - the command options you ran 540 - what occurred 541 - what you expected to occur 542 543 ##### For panics and other crashes, please provide 544 545 - the command you ran 546 - the stack trace generated (if any) 547 - any other relevant information 548 549 ## Cloning the repository 550 ------------------------- 551 552 1. Install [Go](https://golang.org) 553 1. Clone (Forking beforehand for development). 554 1. [Ensure your $GOPATH is set correctly](http://golang.org/cmd/go/#hdr-GOPATH_environment_variable) 555 556 ## Building 557 ------------- 558 559 1. Run `./bin/build` 560 1. The binary will be built into the `./out` directory 561 562 Optionally, you can use `bin/run` to compile and run the executable in one step. 563 564 ## Developing 565 ------------- 566 567 1. Run `go get golang.org/x/tools/cmd/vet` 568 2. Run `go get github.com/xxx ...` to install test dependencies (as you see errors) 569 1. Write a [Ginkgo](https://github.com/onsi/ginkgo) test 570 1. Run `bin/test` and watch the test fail 571 1. Make the test pass 572 1. Submit a pull request 573 574 ## Contributing 575 --------------- 576 577 * We gratefully acknowledge and thank the [current contributors](https://github.com/maximilien/i18n4go/graphs/contributors) 578 * We welcome any and all contributions as Pull Requests (PR) 579 * We also welcome issues and bug report and new feature request. We will address as time permits 580 * Follow the steps above in Developing to get your system setup correctly 581 * Please make sure your PR is passing Travis before submitting 582 * Feel free to email me or the current collaborators if you have additional questions about contributions 583 * Before submitting your first PR, please read and follow steps in [CONTRIBUTING.md](CONTRIBUTING.md) 584 585 ## Managing dependencies 586 ------------------------- 587 588 * All dependencies managed via [gvt](https://github.com/FiloSottile/gvt) 589 590 ### Short `gvt` Guide 591 * If you ever import a new package `foo/bar` (after you `go get foo/bar`, so that foo/bar is in `$GOPATH`), you can type `gvt get `foo/bar` ` to add it to the `vendor` directory. 592 * If you ever remove a dependency or a link becomes deprecated, the easiest way is probably to remove your entire `vendors/foo/bar` directory 593 * To update an existing dependency, you can use `gvt update foo/bar` 594 595 ## Current conventions 596 ----------------------- 597 598 * Basic Go conventions 599 * Strict TDD for any code added or changed 600 * Go fakes when needing to mock objects 601 602 (*) these items are in the works, we will remove the * once they are available