twine

Twine

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

Install

Twine is most easily installed as a Gem.

gem install twine

Twine File Format

Twine stores everything in a single file, the Twine data file. The format of this file is a slight variant of the Git config file format, which itself is based on the old Windows INI file 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 the recommended way of grouping your definitions into smaller, more manageable chunks.

Each grouping section contains N definitions. These definitions start with the key placed within a single pair of square brackets. It then contains a number of key-value pairs, including a comment, a comma-separated list of tags and all of the translations.

Placeholders

Twine supports printf style placeholders with one peculiarity: @ is used for strings instead of s. This is because Twine started out as a tool for iOS and OS X projects.

Tags

Tags are used by Twine as a way to only work with a subset of your definitions at any given point in time. Each definition 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 definitions currently missing tags by executing the validate-twine-file command with the --pedantic option.

When generating a localization file, you can specify which definitions should be included using the --tags option. Provide a comma separated list of tags to match all definitions that contain any of the tags (--tags tag1,tag2 matches all definitions tagged with tag1 or tag2). Provide multiple --tags options to match definitions containing all specified tags (--tags tag1 --tags tag2 matches all definitions tagged with tag1 and tag2). You can match definitions not containing a tag by prefixing the tag with a tilde (--tags ~tag1 matches all definitions not tagged with tag1). All three options are combinable.

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 definition to inherit the values of another definition, you can use a reference. Any property not specified for a definition will be taken from the reference.

Example

…

Supported Output Formats

Twine currently supports the following output formats:

• iOS and OS X String Resources (format: apple)
• Android String Resources (format: android)
  • HTML tags will be escaped by replacing `/dev/null; then twine generate-localization-file twine.txt ./src/main/res/values/generated_strings.xml; fi' exec { executable "sh" args '-c', script } }

preBuild { dependsOn generateLocalizations }

#### Using [jruby](http://jruby.org)

With this approach, developers do not need to manually install ruby, gem, or twine.

Add the following code to `app/build.gradle`:

```groovy
buildscript {
	repositories { jcenter() }

	dependencies {
		/* NOTE: Set your preferred version of jruby here. */
		classpath "com.github.jruby-gradle:jruby-gradle-plugin:1.5.0"
	}
}

apply plugin: 'com.github.jruby-gradle.base'

dependencies {
	/* NOTE: Set your preferred version of twine here. */
	jrubyExec 'rubygems:twine:1.1'
}

task generateLocalizations (type: JRubyExec) {
	dependsOn jrubyPrepare
	jrubyArgs '-S'
	script "twine"
	scriptArgs 'generate-localization-file', 'twine.txt', './src/main/res/values/generated_strings.xml'
}

preBuild {
	dependsOn generateLocalizations
}

User Interface

• Twine TextMate 2 Bundle — This TextMate 2 bundle will make it easier for you to work with Twine files. In particular, it lets you use code folding to easily collapse and expand both definitions and sections.

Extending Twine

If there's a format Twine does not yet support and you're keen to change that, check out the documentation.

Contributors

Many thanks to all of the contributors to the Twine project, including:

• Blake Watters
• bootstraponline
• Ishitoya Kentaro
• Joseph Earl
• Kevin Everets
• Kevin Wood
• Mohammad Hejazi
• Robert Guo
• Sebastian Ludwig
• Sergey Pisarchik
• Shai Shamir