Installation • Usage • Build Script • Migration Guides • Issues • Contributing • License

BartyCrouch

BartyCrouch incrementally updates your Strings files from your Code and from Interface Builder files. "Incrementally" means that BartyCrouch will by default keep both your already translated values and even your altered comments. Additionally you can also use BartyCrouch for machine translating from one language to 40+ other languages. Using BartyCrouch is as easy as running a few simple commands from the command line what can even be automated using a build script within your project.

Requirements

• Xcode 7.3+ and Swift 2.2+
• Xcode Command Line Tools (see here for installation instructions)

Installation

Install Homebrew first if you don't have it already (more about Homebrew here):

$ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Then simply run the commands

$ brew tap flinesoft/bartycrouch
$ brew install flinesoft/bartycrouch/bartycrouch

to install BartyCrouch.

To update to the newest version of BartyCrouch when you have an old version already installed run:

$ brew update
$ brew upgrade flinesoft/bartycrouch/bartycrouch

Usage

Before using BartyCrouch please make sure you have committed your code.

Complete Examples (TL;DR)

With BartyCrouch you can run commands like these:

# Incrementally updates all Strings files of Storyboards/XIBs in project
$ bartycrouch interfaces -p "/absolute/path/to/project"

# Updates `Localizable.strings` files with new keys searching your code for `NSLocalizedString`
$ bartycrouch code -p "/path/to/code/directory" -l "/directory/containing/all/Localizables" -a

# Updates `Localizable.strings` files with new keys searching your code for `YourCustomFunction`. Useful when you are using something else than `NSLocalizedString`
$ bartycrouch code -p "/path/to/code/directory" -l "/directory/containing/all/Localizables" -a -c "YourCustomFunction"

# Machine-translate all empty localization values using English as source language
$ bartycrouch translate -p "/path/to/project" -l en -i "<API_ID>" -s "<API_SECRET>"

Also you can make your life a lot easier by using the build script method described below.

---

Sub Commands Overview

The bartycrouch main command accepts one of the following sub commands:

• interfaces: Incrementally updates Strings files of localized Storyboards and XIBs.
• code: Incrementally updates Localizable.strings files from .h, .m and .swift files.
• translate: Machine-translates values from a source Strings file to all other languages.

Note that each sub command accepts a different set of options. Some of them are required and some optional. You can combine all options with each other to create your own expected behavior. If you're not sure which options are available or required you can always look them up in terminal by running a sub command without options like so:

$ bartycrouch code

Missing required options: ["-p, --path", "-l, --localizables"]

Usage: /usr/local/bin/bartycrouch [options]
  -p, --path:
      Set the base path to recursively search within for code files (.h, .m, .swift).
  -l, --localizables:
      The path to the folder of your output `Localizable.strings` file to be updated.
  ...

---

Options for all Sub Commands

Some options are common to all sub commands and must (if required) or can always be specified.

Path (aka -p, --path) required

For each command BartyCrouch needs to know where it should search for files to do its work. This is done by providing an absolute path to a directory using -p.

Example:

# Finds all Storyboard / XIB files within the specified path as input
$ bartycrouch interfaces -p "/Users/Name/DemoProject/Sources"

Override (aka -o, --override) optional

BartyCrouch keeps non-empty values by default so nothing gets lost (except for keys which are no longer used). If you want to override all your existing translation values you can force BartyCrouch to do this by specifying the -o command.

Example:

# Clears all values of Storyboards / XIBs Strings files
$ bartycrouch interfaces -p "/path/to/project" -o

Verbose (aka -v, --verbose) optional

If you want to know exactly which files BartyCrouch found and updated you can specify the -v command to see a more verbose output.

Example:

$ bartycrouch interfaces -p "/path/to/project" -v

Incrementally updated keys of file '/path/to/project/de.lproj/Main.strings'.
Incrementally updated keys of file '/path/to/project/en.lproj/Main.strings'.
Incrementally updated keys of file '/path/to/project/fr.lproj/Main.strings'.
BartyCrouch: Successfully updated strings file(s) of Storyboard or XIB file.

---

Options for interfaces

Here's an overview of all options available for the sub command interfaces:

• path (required), override and verbose (see Options for all Sub Commands above)
• default-to-base

Default to Base (aka -b, --default-to-base) optional

To use the Base localization values when adding new keys (instead of empty values) simply add the option -b.

Example:

$ bartycrouch interfaces -p "/path/to/project" -b

---

Options for code

Here's an overview of all options available for the sub command code:

• path (required), override and verbose (see Options for all Sub Commands above)
• localizable (required)
• default-to-keys
• additive
• customFunction

Localizable (aka -l, --localizable) required

Specifies the path to the directory which contains all Localizable.strings files within <locale>.lproj folders. BartyCrouch will search for all files named Localizable.strings recursively within the specified path and incrementally update them. Make sure to specify a path with only your projects Localizable.strings files.

Example:

$ bartycrouch code -p "/path/to/code/files" -l "/Users/Name/DemoProject/Sources/Supporting Files"

Default to Keys (aka -k, --default-to-keys) optional

To use the keys as localization values when adding new keys (instead of empty values) simply add the option -k.

Example:

$ bartycrouch code -p "/path/to/code/files" -l "/path/to/localizables" -k

Additive (aka -a, --additive) optional

To prevent BartyCrouch from deleting (seemingly) unused keys you can configure it to only add new keys keeping all existing ones by providing the option -a. This can be useful for example when you want to generate your Localizable.strings using BartyCrouch but use static strings (e.g. with Laurine) once they are added to your Localizables.

Example:

$ bartycrouch code -p "/path/to/code/files", -l "/path/to/localizables" -a

Custom Function (aka -c, --customFunction) optional

If you use a custom function(macro) in your code to localize the strings instead of NSLocalizedString, you may specify it using this option. BartyCrouch will parse the code for the name you give instead of the default NSLocalizedString. Your functions must use the naming and formatting conventions used by the Foundation macros. The parameters for your functions must match the parameters for the corresponding macros exactly. The parsing is done using "genstrings" tool. You may see more in Apple's documentation about it. Look into "Searching for Custom Functions With genstrings" section.

$ bartycrouch code -p "/path/to/code/files" -l "/path/to/Localizables" -c "YourCustomFunction"

---

Options for translate

Here's an overview of all options available for the sub command translate:

• path (required), override and verbose (see Options for all Sub Commands above)
• id (required)
• secret (required)
• locale (required)

ID and Secret (aka -i and -s, --id and --secret) required

BartyCrouch acts as a client for the Microsoft Translator API. In order to use that API you need to register here (the free tier allows for 2 million translations/month). Then you can add a client here which will provide you the id and secret credentials required for machine-translation.

Example:

$ bartycrouch translate -p "/path/to/project" -l en -i "<YOUR_API_ID>" -s "<YOUR_API_SECRET>"

Locale (aka -l, --locale) required

This specifies the source language to use as the input for machine-translation. BartyCrouch can only translate keys which have a value in their source language.

Example:

# Uses Simpliied Chinese as the source language for translating to all other languages
$ bartycrouch translate -p "/path/to/project" -l "zh-Hans" -i "<API_ID>" -s "<API_SECRET>"

---

Build Script

You may want to update your Strings files on each build automatically what you can easily do by adding a run script to your target in Xcode. In order to do this select your target, choose the Build Phases tab and click the + button on the top left corner of that pane. Select New Run Script Phase and copy the following into the text box below the Shell: /bin/sh of your new run script phase:

if which bartycrouch > /dev/null; then
    # Incrementally update all Storyboards/XIBs strings files
    bartycrouch interfaces -p "$PROJECT_DIR"

    # Add new keys to Localizable.strings files from NSLocalizedString in code
    bartycrouch code -p "$PROJECT_DIR" -l "$PROJECT_DIR" -a
else
    echo "warning: BartyCrouch not installed, download it from https://github.com/Flinesoft/BartyCrouch"
fi

Note: Please make sure you commit your code using source control regularly when using the build script method.

If you want to use the machine translation functionality in addition then simply use the following build script instead:

if which bartycrouch > /dev/null; then
    # Incrementally update all Storyboards/XIBs strings files
    bartycrouch interfaces -p "$PROJECT_DIR"

    # Add new keys to Localizable.strings files from NSLocalizedString in code
    bartycrouch code -p "$PROJECT_DIR" -l "$PROJECT_DIR" -a

    # Translate all empty values using the Microsoft Translator API
    bartycrouch translate -p "$PROJECT_DIR" -l en -i "<API_ID>" -s "<API_SECRET>"
else
    echo "warning: BartyCrouch not installed, download it from https://github.com/Flinesoft/BartyCrouch"
fi

It is recommended that you update the -p "$PROJECT_DIR" appearances in this script to point to the directory of your own code only, for example by using -p "$PROJECT_DIR/Sources" instead. Also you should alter -l "$PROJECT_DIR" to a path more specific (e.g. -l "$PROJECT_DIR/Sources/Supporting Files"). This is to make sure BartyCrouch doesn't change any Localizable.strings files within frameworks included using the likes of Carthage or CocoaPods.

---

Exclude specific Views from Localization

Sometimes you may want to ignore some specific views containing localizable texts e.g. because their values are gonna be set programmatically. For these cases you can simply include #bartycrouch-ignore! or the shorthand #bc-ignore! into your value within your base localized Storyboard/XIB file. This will tell BartyCrouch to ignore this specific view when updating your .strings files.

Here's an example of how a base localized view in a XIB file with partly ignored strings might look like:

Migration Guides

This project follows Semantic Versioning.

Please follow the appropriate guide below when upgrading to a new major version of BartyCrouch (e.g. 1.5 -> 2.0).

Upgrade from 2.x to 3.x

• Change structure bartycrouch -s "$BASE_PATH" to bartycrouch interfaces -p "$BASE_PATH"
• Change structure bartycrouch -t "{ id: <API_ID> }|{ secret: <API_SECRET> }" -s "$BASE_PATH" -l en to bartycrouch translate -p "$BASE_PATH" -l en -i "<API_ID>" -s "<API_SECRET>"
• Use automatic file search with -p (was -s before) instead of options -i, -o, -e (those were deleted)
• Rename usages of option "force" (-f) to be "override" (-o)

It is recommended to update your build script to the currently suggested one if you were using it.

Upgrade from 1.x to 2.x

• Change command structure bartycrouch "$BASE_PATH" -a to bartycrouch -s "$BASE_PATH"
• Remove -c option if you were using it, BartyCrouch 2.x creates missing keys by default
• Use the new -t -s -l options instead of adding all Strings files manually, e.g.:

Simplify this build script code

bartycrouch -t $CREDS -i "$EN_PATH/Localizable.strings" -a -c
bartycrouch -t $CREDS -i "$EN_PATH/Main.strings" -a
bartycrouch -t $CREDS -i "$EN_PATH/LaunchScreen.strings" -a
bartycrouch -t $CREDS -i "$EN_PATH/CustomView.strings" -a

by replacing it with this:

bartycrouch -t "$CREDS" -s "$PROJECT_DIR" -l en

Upgrade from 0.x to 1.x

• --input-storyboard and -in were renamed to --input and -i
• --output-strings-files and -out were renamed to --output and -o
• Multiple paths passed to -output are now separated by whitespace instead of comma
  • e.g. -out "path/one,path/two" should now be -o "path/one" "path/two"
• --output-all-languages and -all were renamed to --auto and -a

Contributing

Contributions are welcome. Please just open an Issue on GitHub to discuss a point or request a feature there or send a Pull Request with your suggestion. Please also make sure to write tests for your changes in order to make sure they don't break in the future. Please note that there is a framework target within the project alongside the command line utility target to make testing easier.

License

This library is released under the MIT License. See LICENSE for details.