<commit_before># Twine

Twine is a command line tool for managing your strings and their translations. These strings are all stored in a master text file and then Twine uses this file to import and export strings in a variety of file types, including iOS and Mac OS X `.strings` files, Android `.xml` files, gettext `.po` files, and [jquery-localize][jquerylocalize] `.json` files. This allows individuals and companies to easily share strings across multiple projects, as well as export strings in any format the user wants.

## Install

### As a Gem

Twine is most easily installed as a Gem.

	$ gem install twine

### From Source

You can also run Twine directly from source. However, it requires [rubyzip][rubyzip] in order to create and read standard zip files.

	$ gem install rubyzip
	$ git clone git://github.com/mobiata/twine.git
	$ cd twine
	$ ./twine --help

Make sure you run the `twine` executable at the root of the project as it properly sets up your Ruby library path. The `bin/twine` executable does not.

## String File Format

Twine stores all of its strings in a single file. The format of this file is a slight variant of the [Git][git] config file format, which itself is based on the old [Windows INI file][INI] format. The entire file is broken up into sections, which are created by placing the section name between two pairs of square brackets. Sections are optional, but they are a recommended way of breaking your strings into smaller, more manageable chunks.

Each grouping section contains N string definitions. These string definitions start with the string key placed within a single pair of square brackets. This string definition then contains a number of key-value pairs, including a comment, a comma-separated list of tags (which are used by Twine to select a subset of strings), and all of the translations.

### Tags

Tags are used by Twine as a way to only work with a subset of your strings at any given point in time. Each string can be assigned zero or more tags which are separated by commas. Tags are optional, though highly recommended. You can get a list of all strings currently missing tags by executing the `validate-strings-file` command.

### Whitespace

Whitepace in this file is mostly ignored. If you absolutely need to put spaces at the beginning or end of your translated string, you can wrap the entire string in a pair of `` ` `` characters. If your actual string needs to start *and* end with a grave accent, you can wrap it in another pair of `` ` `` characters. See the example, below.

### References

If you want a key to inherit the values of another key, you can use a reference. Any property not specified for a key will be taken from the reference.

### Example

	[[General]]
		[yes]
			en = Yes
			es = Sí
			fr = Oui
			ja = はい
		[no]
			en = No
			fr = Non<commit_msg>Added short paragraph about placeholders to README.<commit_after># Twine

Twine is a command line tool for managing your strings and their translations. These strings are all stored in a master text file and then Twine uses this file to import and export strings in a variety of file types, including iOS and Mac OS X `.strings` files, Android `.xml` files, gettext `.po` files, and [jquery-localize][jquerylocalize] `.json` files. This allows individuals and companies to easily share strings across multiple projects, as well as export strings in any format the user wants.

## Install

### As a Gem

Twine is most easily installed as a Gem.

	$ gem install twine

### From Source

You can also run Twine directly from source. However, it requires [rubyzip][rubyzip] in order to create and read standard zip files.

	$ gem install rubyzip
	$ git clone git://github.com/mobiata/twine.git
	$ cd twine
	$ ./twine --help

Make sure you run the `twine` executable at the root of the project as it properly sets up your Ruby library path. The `bin/twine` executable does not.

## String File Format

Twine stores all of its strings in a single file. The format of this file is a slight variant of the [Git][git] config file format, which itself is based on the old [Windows INI file][INI] format. The entire file is broken up into sections, which are created by placing the section name between two pairs of square brackets. Sections are optional, but they are a recommended way of breaking your strings into smaller, more manageable chunks.

Each grouping section contains N string definitions. These string definitions start with the string key placed within a single pair of square brackets. This string definition then contains a number of key-value pairs, including a comment, a comma-separated list of tags (which are used by Twine to select a subset of strings), and all of the translations.

### Placeholders

Twine supports [`printf` style placeholders](https://en.wikipedia.org/wiki/Printf_format_string) with one peculiarity: `@` is used for strings instead of `s`.

### Tags

Tags are used by Twine as a way to only work with a subset of your strings at any given point in time. Each string can be assigned zero or more tags which are separated by commas. Tags are optional, though highly recommended. You can get a list of all strings currently missing tags by executing the `validate-strings-file` command.

### Whitespace

Whitepace in this file is mostly ignored. If you absolutely need to put spaces at the beginning or end of your translated string, you can wrap the entire string in a pair of `` ` `` characters. If your actual string needs to start *and* end with a grave accent, you can wrap it in another pair of `` ` `` characters. See the example, below.

### References

If you want a key to inherit the values of another key, you can use a reference. Any property not specified for a key will be taken from the reference.

### Example

	[[General]]
		[yes]
			en = Yes
			es = Sí
			fr = Oui
			ja = はい
		[no]
			en = No
			fr = Non
{'fraction_non_alphanumeric': 0.0560081466395112, 'fraction_numerical': 0.0, 'mean_word_length': 3.93964794635373, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 1, 'lorem ipsum': 0, 'www.': 0, 'xml': 2}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3761218', 'n_tokens_mistral': 1535, 'n_tokens_neox': 1469, 'n_words': 945}