PhraseApp

PhraseApp is a translation management software. Set up a professional translation process to boost the quality of your translations with our powerful In-Context Editor or simply share and edit locale files with your team.

You can order professional translations through PhraseApp or work with your own translators. Our platform supports various programming languages and frameworks. Such as Ruby on Rails, Symfony, Zend Framework, iOS, Android and many more.

This ruby gem allows you to integrate PhraseApp into your project and access your locale files through the PhraseApp API.

Try out PhraseApp for free and start translating your app!

In-Context Editor

PhraseApp comes with an In-Context editor that allows you to translate directly on your website. See our documentation on how to set it up: In-Context Editor Setup.

Supported Formats

You can manage your locale files with PhraseApp if you use one of the following formats:

Ruby/Rails YAML
Gettext
Gettext Template
Android Strings
iOS Localizable Strings
XLIFF
Qt Phrase Book
Qt Translation Source
Chrome JSON i18n
Simple JSON
Nested JSON
GoI18n JSON
i18n-node-2 JSON
.NET ResX
Windows Phone ResX
Windows 8 Resource
INI
Java Properties .properties
Java Properties XML
Objective-C/Cocoa Property List
Symfony YAML
Symfony2 YAML (Beta)
TMX Translation Memory eXchange
Excel XLSX (Beta)
CSV
PHP Array
Zendesk CSV
Laravel/Flask PHP
Angular Translate
Mozilla Properties
Play Properties

Usage

This command line client is a Ruby gem. If you haven't installed Ruby on your system yet, we have put together a handy tutorial for you.

You don't have to use this client but can also use the API directly.

Installation

Install the gem via gem install

gem install phrase

or add it to your Gemfile when using bundler:

gem 'phrase'

and install it

$ bundle install

That's it!

Initialization

Before you can use the phrase command line client you have to set up some configuration data. When using Rails we recommend using the Rails generator we provide. For all other environments you can use a simple command to initialize the setup.

To initialize phrase, your project auth token (secret) is required. You can find the auth token next to the project on your project overview.

When using Rails

Install phrase by executing the Rails generator:

bundle exec rails generate phrase:install --auth-token=<YOUR_TOKEN>

This will:

create a phrase.rb initializer file in ./config/initializers/
initialize your phrase project by creating a default locale in PhraseApp
create a .phrase configuration file containing the secret

Using the generator will automatically prepare your Rails application for use with the In-Context-Editor.

Without Rails

You can use the phrase init command to initialize your project:

phrase init --secret=<YOUR_TOKEN>

This will:

initialize your phrase project by creating a default locale in PhraseApp
create a .phrase configuration file containing the secret

Pushing Locale Files

Push your localization files to PhraseApp by using the push command:

phrase push FILE|DIRECTORY

This will push all files found in the given directory or push only the file if the given path points to a file. The path falls back to ./config/locales, the default localization file path in Ruby on Rails applications.

--recursive, -R

To push all files in a given directory recursively you can use the --recursive parameter:
```
  phrase push </path/to/file.extension> --recursive
```
--tags

Attach one or multiple tags with your file upload. All keys added by the push will be tagged with the specified tags:
```
  phrase push --tags=foo,bar
```
--locale

Some formats do not contain information about their content's locale. These formats (e.g. Java Properties) require you to specify the locale (name) with the push command:
```
  phrase push messages.properties --locale=en
```
--format

Specify the format of the files you want to push. We usually try to guess it by evaluating the file name but sometimes you need to tell us more:
```
  phrase push messages.json --format=simple_json
```
For a full list of all supported formats check our format guide.
--force-update-translations

When pushing files to PhraseApp, we only add new resources (keys and translations) by default. Use this flag if you want to override existing translations as well.
```
  phrase push most-recent.yml --force-update-translations
```
Please note that we do not delete resources from your project even when using this option. Still you have to make sure that your file contains the most recent translations since all translations in your project will be updated with the file content!
--skip-unverification

When using the --force-update-translations flag (see above) we will automatically unverify updated translations if configured in your workflow. Use this flag to prevent all translations being unverified. This option is great if you have copy&replaced strings in your file and just want to update all translations:
```
  phrase push most-recent.yml --force-update-translations --skip-unverification
```
--skip-upload-tags

When you push translations we will automatically attach new keys to an upload tag. To prevent this from happening, you can use this option:
```
  phrase push my-file.yml --skip-upload-tags
```
This can be very useful if you replace your content very often and do not want to create hundreds of upload-tags.
--convert-emoji

When you use Emoji symbols in your locale files (i.e. in iOS Localizable strings files) you can tell us to convert them to more readable symbols:
```
  phrase push Localizable.strings --convert-emoji
```
Please note that you should only use this option if your file definitely contains Emoji symbols since it slows down the upload time quite a bit.
--secret

Your project auth token. You can find the auth token in your project overview or project settings form. This will fall back to the token stored in your .phrase config file.

Pulling Locale files

Pull your most recent locale files by using the pull command:

phrase pull

This will pull localization files for all of your locales available in the current project. Files are by default stored at ./phrase/locales in YAML format.

--format

Specify the format you want to download your files in:
```
  phrase pull en --format=simple_json
```
For a full list of all supported formats check our format guide.
--target

Specify where you want to download the files to:
```
  phrase pull fr --target="./config/locales"
```
By default, files will be downloaded to ./phrase/locales.
--tag

Limit results to a given tag instead of downloading all translations:
```
  phrase pull de --tag=feature-messenger-v2
```
--updated-since

Limit results to translations being updated after the given date and time (UTC) in the format YYYYMMDDHHMMSS:
```
  phrase pull en --updated-since=20140601123000
```
--include-empty-translations

By default we will only return translated keys in the file. Use this flag to include empty translations as well:
```
  phrase pull en --include-empty-translations
```
--convert-emoji

When you use Emoji symbols in your translations you can tell us to convert them back to correctly encoded symbols:
```
  phrase pull --convert-emoji
```
Please note that you should only use this option if your translations definitely contains Emojis since it slows down the download time a bit.
--encoding

Set the encoding for your localization files to UTF-8, UTF-16 or Latin-1.
```
  phrase pull --encoding=UTF-8
```
Please note that the encodings only work for a handful of formats like IOS .strings or Java .properties. The default will be UTF-8. If none is provided the default encoding of the formats is used.
--skip-unverified-translations

By default all translations are downloaded. Use this flag to skip all unverified translations.
```
  phrase pull --skip-unverified-translations
```
--secret

Your project auth token. You can find the auth token in your project overview or project settings form. This will fall back to the token stored in your .phrase config file.

Advanced configuration

The phrase init command allows several advanced configuration options to further customize the setup:

--default-locale

You can specify a locale that should be used as the default locale when setting up your PhraseApp project (default is en).
```
  phrase init --secret=<YOUR_TOKEN> --default-locale=fr
```
--default-format

Specify a format that should be used as the default format when downloading files (default is yml). For a full list of all supported formats check our format guide.
--domain

Set a domain for use with Gettext translation files (default is phrase).
--locale-directory

Set the directory that contains your source locales (used by the phrase push command). Allows placeholders.
--locale-filename

Set the filename for files you download from PhraseApp via phrase pull. Allows placeholders.
--default-target

Set the target directly to store your localization files retrieved by phrase pull. Allows placeholders.

These options will be stored in your .phrase config file where you can edit them later on as well.

Allowed placeholders for advanced configuration

Some advanced configuration options support placeholders. These will be replaced with the actual content. This allows you to create more flexible path and filename settings.

Placeholder	Description	Default
<domain>	Name of the domain	phrase
<format>	Format name/identifier	yml
<locale>	Locale name	en
<locale.name>	Locale name	en
<locale.code>	Locale code	-

For example you can specify a different file name for files you retrieve via the phrase pull command:

phrase init --secret=<YOUR_TOKEN> --locale-filename="<locale.name>.yml"

weynsee / phrase