Installation • Configuration • Usage • Build Script • Donation • 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 60+ 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.

Checkout this blog post to learn how you can effectively use BartyCrouch in your projects.

Requirements

• Xcode 11.4+ & Swift 5.2+
• Xcode Command Line Tools (see here for installation instructions)

Getting Started

Installation

brew install bartycrouch

brew upgrade bartycrouch

mint install Flinesoft/BartyCrouch

Configuration

To configure BartyCrouch for your project, first create a configuration file within your projects root directory. BartyCrouch can do this for you:

bartycrouch init

Now you should have a file named

.bartycrouch.toml

[update]
tasks = ["interfaces", "code", "transform", "normalize"]

[update.interfaces]
paths = ["."]
defaultToBase = false
ignoreEmptyStrings = false
unstripped = false
[update.code]
codePaths = ["."]
localizablePaths = ["."]
defaultToKeys = false
additive = true
unstripped = false
[update.transform]
codePaths = ["."]
localizablePaths = ["."]
transformer = "foundation"
supportedLanguageEnumPath = "."
typeName = "BartyCrouch"
translateMethodName = "translate"
[update.normalize]
paths = ["."]
sourceLocale = "en"
harmonizeWithSource = true
sortByKeys = true
[lint]
paths = ["."]
duplicateKeys = true
emptyValues = true

This is the default configuration of BartyCrouch and should work for most projects as is. In order to use BartyCrouch to its extent, it is recommended though to consider making the following changes:

1. To speed it up significantly, provide more specific paths for any key containing

   path

   if possible (especially in the

   update.transform

   section, e.g.

   ["App/Sources"]

   for

   codePaths

   or

   ["App/Supporting Files"]

   for

   supportedLanguageEnumPaths

   ).
2. Remove the

   code

   task if your project is Swift-only and you use the new

   transform

   update task.
3. If you are using SwiftGen with the

   structured-swift4

   template, you will probably want to use the

   transform

   task and change its

   transformer

   option to

   swiftgenStructured

   .
4. If you decided to use the

   transform

   task, create a new file in your project (e.g. under

   SupportingFiles

   ) named

   BartyCrouch.swift

   and copy the following code:

//  This file is required in order for the `transform` task of the translation helper tool BartyCrouch to work.
//  See here for more details: https://github.com/Flinesoft/BartyCrouch

import Foundation
enum BartyCrouch {
    enum SupportedLanguage: String {
        // TODO: remove unsupported languages from the following cases list & add any missing languages
        case arabic = "ar"
        case chineseSimplified = "zh-Hans"
        case chineseTraditional = "zh-Hant"
        case english = "en"
        case french = "fr"
        case german = "de"
        case hindi = "hi"
        case italian = "it"
        case japanese = "ja"
        case korean = "ko"
        case malay = "ms"
        case portuguese = "pt-BR"
        case russian = "ru"
        case spanish = "es"
        case turkish = "tr"
    }
static func translate(key: String, translations: [SupportedLanguage: String], comment: String? = nil) -> String {
    let typeName = String(describing: BartyCrouch.self)
    let methodName = #function

    print(
        "Warning: [BartyCrouch]",
        "Untransformed \(typeName).\(methodName) method call found with key '\(key)' and base translations '\(translations)'.",
        "Please ensure that BartyCrouch is installed and configured correctly."
    )

    // fall back in case something goes wrong with BartyCrouch transformation
    return "BC: TRANSFORMATION FAILED!"
}
}

1. If you don't develop in English as the first localized language, you should update the

   sourceLocale

   of the

   normalize

   task.
2. If you want to use the machine translation feature of BartyCrouch, add

   translate

   to the tasks list at the top and copy the following section into the configuration file with

   secret

   replaced by your Microsoft Translator Text API Subscription Key:

[update.translate]
paths = "."
secret = ""
sourceLocale = "en"

Usage

Before using BartyCrouch please make sure you have committed your code. Also, we highly recommend using the build script method described below.

bartycrouch

• update

  : Updates your

  .strings

  file contents according to your configuration.

• lint

  : Checks your

  .strings

  file contents for empty values & duplicate keys.

Also the following command line options can be provided:

• -v

  ,

  --verbose

  : Prints more detailed information about the executed command.

• -x

  ,

  --xcode-output

  : Prints warnings & errors in Xcode compatible format.

• -w

  ,

  --fail-on-warnings

  : Returns a failed status code if any warning is encountered.

• -p

  ,

  --path

  : Specifies a different path than current to run BartyCrouch from there.

update

subcommand

The update subcommand can be run with one or multiple of the following tasks:

• interfaces

  : Updates

  .strings

  files of Storyboards & XIBs.

• code

  : Updates

  Localizable.strings

  file from

  NSLocalizedString

  entries in code.

• transform

  : A mode where BartyCrouch replaces a specific method call to provide translations in multiple languages in a single line. Only supports Swift files.

• translate

  : Updates missing translations in other languages than the source language.

• normalize

  : Sorts & cleans up

  .strings

  files.

In order to configure which tasks are executed, edit this section in the config file:

[update]
tasks = ["interfaces", "code", "transform", "normalize"]

lint

subcommand

The lint subcommand was designed to analyze a project for typical translation issues. The current checks include:

• duplicateKeys

  : Finds duplicate keys within the same file.

• emptyValues

  : Finds empty values for any language.

Note that the

lint

• In Xcode the

  -x

  or

  --xcode-output

  command line argument should be used to get warnings which point you directly to the found issue.
• When running on the CI you should specify the

  -w

  or

  --fail-on-warnings

  argument to make sure BartyCrouch fails if any warnings are encountered.

Localization Workflow via

transform

When the

transform

1. Instead of

   NSLocalizedString

   calls you can use

   BartyCrouch.translate

   and specify a key, translations (if any) and optionally a comment. For example:

self.title = BartyCrouch.translate(key: "onboarding.first-page.header-title",  translations: [.english: "Welcome!"])

1. Once you build your app, BartyCrouch will automatically add the new translation key to all your

   Localizable.strings

   files and add the provided translations as values for the provided languages.
2. Additionally, during the same build BartyCrouch will automatically replace the above call to

   BartyCrouch.translate

   with the proper translation call, depending on your

   transformer

   option setting.

The resulting code depends on your

transformer

When set to

foundation

self.title = NSLocalizedString("onboarding.first-page.header-title", comment: "")

When set to

swiftgenStructured

self.title = L10n.Onboarding.FirstPage.headerTitle

Advantages of

transform

code

NSLocalizedString

L10n

Disadvantages of

transform

code

code

NOTE: As of version 4.x of BartyCrouch formatted localized Strings are not supported by this automatic feature.

Build Script

In order to truly profit from BartyCrouch's ability to update & lint your

.strings

Build Phases

New Run Script Phase

Shell: /bin/sh

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

Next, make sure the BartyCrouch script runs before the steps

Compiling Sources

SwiftGen

Target Dependencies

Now BartyCrouch will be run on each build and you won't need to call it manually ever (again). Additionally, all your co-workers who don't have BartyCrouch installed will see a warning with a hint on how to install it.

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

Exclude specific Views / NSLocalizedStrings from Localization

Sometimes you may want to ignore some specific views containing localizable texts e.g. because their values are going to be set programmatically.

For these cases you can simply include

#bartycrouch-ignore!

#bc-ignore!

#bc-ignore!

This will tell BartyCrouch to ignore this specific view when updating your

.strings

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

Here's an example with the alternative comment variant:

You can also use

#bc-ignore!

NSLocalizedString

Localizable.strings

.stringsdict

For example you can do something like this:

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

The

%d minute(s) ago

Donation

BartyCrouch was brought to you by Cihat Gündüz in his free time. If you want to thank me and support the development of this project, please make a small donation on PayPal. In case you also like my other open source contributions and articles, please consider motivating me by becoming a sponsor on GitHub or a patron on Patreon.

Thank you very much for any donation, it really helps out a lot! 💯

Migration Guides

See the file MIGRATION_GUIDES.md.

Contributing

Contributions are welcome. Feel free to open an issue on GitHub with your ideas or implement an idea yourself and post a pull request. If you want to contribute code, please try to follow the same syntax and semantic in your commit messages (see rationale here). Also, please make sure to add an entry to the

CHANGELOG.md

After Release Checklist:

1. Run

   make portable_zip

   to generate

   .build/release/portable_bartycrouch.zip

2. Create new release with text from new

   CHANGELOG.md

   section & attach

   portable_bartycrouch.zip

   as binary
3. Run

   pod trunk push

   to make a new release known to CocoaPods
4. Update

   tag

   and

   revision

   in

   Formula/bartycrouch.rb

   , commit & push change
5. Run

   brew bump-formula-pr bartycrouch --tag= --revision=

License

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