BartyCrouch

BartyCrouch is a CLI tool for managing iOS/macOS localizations. It primarily supports two subcommands:

• update: Synchronizes your .strings files with your code and interfaces based on your configuration.
• lint: Analyzes your .strings files for common issues like duplicateKeys or emptyValues.

Important: Always commit your code before running BartyCrouch to avoid losing changes during automated updates.

When upgrading to BartyCrouch 1.x, note these flag renames and syntax changes:

• Input Flag: --input-storyboard and -in are now --input and -i.
• Output Flag: --output-strings-files and -out are now --output and -o.
• Output Path Separator: Multiple paths passed to -o must now be separated by whitespace instead of commas.
  • Old: -out "path/one,path/two"
  • New: -o "path/one" "path/two"
• Auto Flag: --output-all-languages and -all are now --auto and -a.

To use BartyCrouch, ensure your environment meets the following requirements:

• Xcode: 14+
• Swift: 5.7+
• Xcode Command Line Tools: Must be installed.
• Xcode 15+ Users: You must set User Script Sandboxing to NO in your target's "Build Settings" tab to allow the tool to run within build scripts.

To run the translation tests, you must provide an API key by copying the secrets sample file to the expected location:

cp Tests/BartyCrouchTranslatorTests/Secrets/secrets.json.sample Tests/BartyCrouchTranslatorTests/Secrets/secrets.json

If you need to prevent BartyCrouch from localizing specific views or code entries, use the following markers:

In Storyboards/XIBs:

• Add #bartycrouch-ignore! or #bc-ignore! to the value of the view.
• Alternatively, add #bc-ignore! to the "Comment For Localizer" field in the utilities pane.

In Swift Code:

• Add #bc-ignore! to the comment parameter of an NSLocalizedString macro. This is useful for strings that should be handled by a .stringsdict file instead of .strings.

func updateTimeLabel(minutes: Int) {
  String.localizedStringWithFormat(NSLocalizedString("%d minute(s) ago", comment: "pluralized and localized minutes #bc-ignore!"), minutes)
}

When upgrading to BartyCrouch 4.x, note the following breaking changes:

• Subcommand Consolidation: Most subcommands have been bundled into the update subcommand. The lint subcommand remains separate.
• Configuration Shift: Instead of passing specific subcommands and options via the CLI, you should now use the .bartycrouch.toml configuration file.
• Build Scripts: Update your build scripts to the new simplified version. Ensure the BartyCrouch step is executed early in your build process.
• Default Options: The --override-comments (-c) and --extract-loc-strings (-e) options for the code subcommand are now enabled by default and no longer need to be configured.
• Localization Workflow: Consider adopting the new transform task for your localization workflow, either as a replacement for or an addition to the code task.

To automate localization updates and linting, add BartyCrouch as a Run Script Phase in your Xcode target:

1. Select your target in Xcode.
2. Go to the Build Phases tab.
3. Click the + button and select New Run Script Phase.
4. Set the shell to /bin/sh and paste the following:

export PATH="$PATH:/opt/homebrew/bin"

if which bartycrouch > /dev/null; then
    bartycrouch update -x
    bartycrouch lint -x
else
    echo "warning: BartyCrouch not installed, download it from https://github.com/FlineDev/BartyCrouch"
fi

5. Crucial: Drag the script phase so it runs before Compiling Sources (and SwiftGen if used). For example, place it right after Target Dependencies.

When upgrading to BartyCrouch 2.x, follow these instructions:

• Command Structure: Change bartycrouch "$BASE_PATH" -a to bartycrouch -s "$BASE_PATH".
• Remove Comment Option: Remove the -c option; BartyCrouch 2.x now creates missing keys by default.
• Simplify Strings Handling: Instead of manually adding every .strings file, use the -t, -s, and -l options to target a project directory and language.

Example Transformation:

Old way (manual file addition):

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

New way (simplified):

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

You can install BartyCrouch using Homebrew or Mint.

Via Homebrew: To install for the first time:

brew install bartycrouch

To update an existing installation:

brew upgrade bartycrouch

Via Mint: To install or update to the latest version:

mint install FlineDev/BartyCrouch