Skip to content

Commit

Permalink
Merge pull request #317 from Goooler/update-readme-code-blocks
Browse files Browse the repository at this point in the history
Update code blocks in README
  • Loading branch information
scelis authored Feb 21, 2025
2 parents 2778ceb + e2f8cc2 commit c8f01a5
Showing 1 changed file with 38 additions and 18 deletions.
56 changes: 38 additions & 18 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,9 @@ Twine is a command line tool for managing your strings and their translations. T

Twine is most easily installed as a Gem.

$ gem install twine
```sh
gem install twine
```

## Twine File Format

Expand Down Expand Up @@ -100,55 +102,71 @@ If you would like to enable Twine to create localization files in another format

This command creates a localization file from the Twine data file. If the output file would not contain any translations, Twine will exit with an error.

$ twine generate-localization-file /path/to/twine.txt values-ja.xml --tags common,app1
$ twine generate-localization-file /path/to/twine.txt Localizable.strings --lang ja --tags mytag
$ twine generate-localization-file /path/to/twine.txt all-english.strings --lang en
```sh
twine generate-localization-file /path/to/twine.txt values-ja.xml --tags common,app1
twine generate-localization-file /path/to/twine.txt Localizable.strings --lang ja --tags mytag
twine generate-localization-file /path/to/twine.txt all-english.strings --lang en
```

#### `generate-all-localization-files`

This command is a convenient way to call [`generate-localization-file`](#generate-localization-file) multiple times. It uses standard conventions to figure out exactly which files to create given a parent directory. For example, if you point it to a parent directory containing `en.lproj`, `fr.lproj`, and `ja.lproj` subdirectories, Twine will create a `Localizable.strings` file of the appropriate language in each of them. However, files that would not contain any translations will not be created; instead warnings will be logged to `stderr`. This is often the command you will want to execute during the build phase of your project.

$ twine generate-all-localization-files /path/to/twine.txt /path/to/project/locales/directory --tags common,app1
```sh
twine generate-all-localization-files /path/to/twine.txt /path/to/project/locales/directory --tags common,app1
```

#### `consume-localization-file`

This command slurps all of the translations from a localization file and incorporates the translated strings into the Twine data file. This is a simple way to incorporate any changes made to a single file by one of your translators. It will only identify definitions that already exist in the data file.

$ twine consume-localization-file /path/to/twine.txt fr.strings
$ twine consume-localization-file /path/to/twine.txt Localizable.strings --lang ja
$ twine consume-localization-file /path/to/twine.txt es.xml
```sh
twine consume-localization-file /path/to/twine.txt fr.strings
twine consume-localization-file /path/to/twine.txt Localizable.strings --lang ja
twine consume-localization-file /path/to/twine.txt es.xml
```

#### `consume-all-localization-files`

This command reads in a folder containing many localization files. These files should be in a standard folder hierarchy so that Twine knows the language of each file. When combined with the `--developer-language`, `--consume-comments`, and `--consume-all` flags, this command is a great way to create your initial Twine data file from an existing project. Just make sure that you create a blank Twine data file first!

$ twine consume-all-localization-files twine.txt Resources/Locales --developer-language en --consume-all --consume-comments
```sh
twine consume-all-localization-files twine.txt Resources/Locales --developer-language en --consume-all --consume-comments
```

#### `generate-localization-archive`

This command is a convenient way to generate a zip file containing files created by the [`generate-localization-file`](#generate-localization-file) command. If a file would not contain any translated strings, it is skipped and a warning is logged to `stderr`. This command can be used to create a single zip containing a large number of translations in all languages which you can then hand off to your translation team.

$ twine generate-localization-archive /path/to/twine.txt LocDrop1.zip
$ twine generate-localization-archive /path/to/twine.txt LocDrop2.zip --lang en,fr,ja,ko --tags common,app1
```sh
twine generate-localization-archive /path/to/twine.txt LocDrop1.zip
twine generate-localization-archive /path/to/twine.txt LocDrop2.zip --lang en,fr,ja,ko --tags common,app1
```

#### `consume-localization-archive`

This command is a convenient way of taking a zip file and executing the [`consume-localization-file`](#consume-localization-file) command on each file within the archive. It is most often used to incorporate all of the changes made by the translation team after they have completed work on a localization archive.

$ twine consume-localization-archive /path/to/twine.txt LocDrop2.zip
```sh
twine consume-localization-archive /path/to/twine.txt LocDrop2.zip
```

#### `validate-twine-file`

This command validates that the Twine data file can be parsed, contains no duplicate keys, and that no key contains invalid characters. It will exit with a non-zero status code if any of those criteria are not met.

$ twine validate-twine-file /path/to/twine.txt
```sh
twine validate-twine-file /path/to/twine.txt
```

## Creating Your First Twine Data File

The easiest way to create your first Twine data file is to run the [`consume-all-localization-files`](#consume-all-localization-files) command. The one caveat is to first create a blank file to use as your starting point. Then, just point the `consume-all-localization-files` command at a directory in your project containing all of your localization files.

$ touch twine.txt
$ twine consume-all-localization-files twine.txt Resources/Locales --developer-language en --consume-all --consume-comments --format apple/android/gettext/jquery/django/tizen/flash
```sh
touch twine.txt
twine consume-all-localization-files twine.txt Resources/Locales --developer-language en --consume-all --consume-comments --format apple/android/gettext/jquery/django/tizen/flash
````

## Twine and Your Build Process

Expand All @@ -159,7 +177,9 @@ It is easy to incorporate Twine right into your iOS and OS X app build processes
1. In your project folder, create all of the `.lproj` directories that you need. It does not really matter where they are. We tend to put them in `Resources/Locales/`.
2. Run the [`generate-all-localization-files`](#generate-all-localization-files) command to create all of the `.strings` files you need in these directories. For example,

$ twine generate-all-localization-files twine.txt Resources/Locales/ --tags tag1,tag2
```shell
twine generate-all-localization-files twine.txt Resources/Locales/ --tags tag1,tag2
```

Make sure you point Twine at your data file, the directory that contains all of your `.lproj` directories, and the tags that describe the definitions you want to use for this project.
3. Drag the `Resources/Locales/` directory to the Xcode project navigator so that Xcode knows to include all of these `.strings` files in your build.
Expand All @@ -176,7 +196,7 @@ Now, whenever you build your application, Xcode will automatically invoke Twine
Add the following code to `app/build.gradle`:
```
```groovy
task generateLocalizations {
String script = 'if hash twine 2>/dev/null; then twine generate-localization-file twine.txt ./src/main/res/values/generated_strings.xml; fi'
exec {
Expand All @@ -196,7 +216,7 @@ With this approach, developers do not need to manually install ruby, gem, or twi
Add the following code to `app/build.gradle`:
```
```groovy
buildscript {
repositories { jcenter() }
Expand Down

0 comments on commit c8f01a5

Please sign in to comment.