本地化/I18n:从 .swift、.h、.m(m)、.storyboard 或 .xib 文件增量更新/翻译字符串文件
巴蒂克劳奇
BartyCrouch 以增量方式从代码和接口生成器文件更新字符串文件。“增量”意味着BartyCrouch将默认保留您已经翻译的值,甚至保留您更改的评论。此外,您还可以使用BartyCrouch从一种语言机器翻译成60 +其他语言。使用 BartyCrouch 就像从命令行运行一些简单的命令一样简单,甚至可以在项目中使用构建脚本自动执行。
查看这篇博文,了解如何在项目中有效地使用 BartyCrouch。
要求
- Xcode 13.0+ & Swift 5.5+
- Xcode 命令行工具(有关安装说明,请参阅此处)
开始
安装
通过自制
To install Bartycrouch the first time, simply run the command:
要在已安装旧版本时更新到最新版本的 BartyCrouch,请运行:
通过薄荷
To install or update to the latest version of BartyCrouch simply run this command:
配置
要为您的项目配置 BartyCrouch,请先在项目根目录中创建一个配置文件。BartyCrouch可以为你做到这一点:
bartycrouch init
现在,您应该有一个以以下内容命名的文件:.bartycrouch.toml
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:
- To speed it up significantly, provide more specific paths for any key containing if possible (especially in the section, e.g. for or for ).
path
update.transform
["App/Sources"]
codePaths
["App/Supporting Files"]
supportedLanguageEnumPaths
- Remove the task if your project is Swift-only and you use the new
transform
update task.code
- If you are using SwiftGen with the template, you will probably want to use the task and change its option to .
structured-swift4
transform
transformer
swiftgenStructured
- If you decided to use the task, create a new file in your project (e.g. under ) named and copy the following code:
transform
SupportingFiles
BartyCrouch.swift
- If you don't develop in English as the first localized language, you should update the of the task.
sourceLocale
normalize
- If you want to use the machine translation feature of BartyCrouch, add to the tasks list at the top and copy the following section into the configuration file with replaced by your Microsoft Translator Text API Subscription Key:
translate
secret
Usage
Before using BartyCrouch please make sure you have committed your code. Also, we highly recommend using the build script method described below.
bartycrouch
accepts one of the following sub commands:
update
: Updates your file contents according to your configuration..strings
lint
: Checks your file contents for empty values & duplicate keys..strings
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 files of Storyboards & XIBs..strings
code
: Updates file from entries in code.Localizable.strings
NSLocalizedString
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 files..strings
In order to configure which tasks are executed, edit this section in the config file:
Options for interfaces
paths
: The directory / directories to search for Storyboards & XIB files.defaultToBase
: Add Base translation as value to new keys.ignoreEmptyStrings
: Doesn't add views with empty values.unstripped
: Keeps whitespaces at beginning & end of Strings files.
Options for code
codePaths
: The directory / directories to search for Swift code files.localizablePaths
: The enclosing path(s) containing the localized files.Localizable.strings
defaultToKeys
: Add new keys both as key and value.additive
: Prevents cleaning up keys not found in code.customFunction
: Use alternative name to .NSLocalizedString
customLocalizableName
: Use alternative name for .Localizable.strings
unstripped
: Keeps whitespaces at beginning & end of Strings files.plistArguments
: Use a plist file to store all the code files for the ExtractLocStrings tool. (Recommended for large projects.)
Options for transform
codePaths
: The directory / directories to search for Swift code files.localizablePaths
: The enclosing path(s) containing the localized files.Localizable.strings
transformer
: Specifies the replacement code. Use for or for entries.foundation
NSLocalizedString
swiftgenStructured
L10n
supportedLanguageEnumPath
: The enclosing path containing the enum.SupportedLanguage
typeName
: The name of the type enclosing the enum and translate method.SupportedLanguage
translateMethodName
: The name of the translate method to be replaced.customLocalizableName
: Use alternative name for .Localizable.strings
Options for translate
paths
: The directory / directories to search for Strings files.translator
: Specifies the translation API. Use or .microsoftTranslator
deepL
secret
: Your Microsoft Translator Text API Subscription Key or Authentication Key for DeepL API.sourceLocale
: The source language to translate from.
Options for normalize
paths
: The directory / directories to search for Strings files.sourceLocale
: The source language to harmonize keys of other languages with.harmonizeWithSource
: Synchronizes keys with source language.sortByKeys
: Alphabetically sorts translations by their keys.
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 command can be used both on CI and within Xcode via the build script method:lint
- In Xcode the or command line argument should be used to get warnings which point you directly to the found issue.
-x
--xcode-output
- When running on the CI you should specify the or argument to make sure BartyCrouch fails if any warnings are encountered.
-w
--fail-on-warnings
Localization Workflow via transform
When the update task is configured (see recommended step 4 in the Configuration section above) and you are using the build script method, you can use the following simplified process for writing localized code during development:transform
- Instead of calls you can use and specify a key, translations (if any) and optionally a comment. For example:
NSLocalizedString
BartyCrouch.translate
- Once you build your app, BartyCrouch will automatically add the new translation key to all your files and add the provided translations as values for the provided languages.
Localizable.strings
- Additionally, during the same build BartyCrouch will automatically replace the above call to with the proper translation call, depending on your option setting.
BartyCrouch.translate
transformer
The resulting code depends on your option setting:transformer
When set to , the above code will transform to:foundation
When set to it will transform to:swiftgenStructured
Advantages of transform
over the code
task:
- You can provide translations for keys without switching to the Strings files.
- In case you use SwiftGen, you don't need to replace calls to with calls manually after running BartyCrouch.
NSLocalizedString
L10n
- Can be combined with the machine translation feature to provide a source language translation in code and let BartyCrouch translate it to all supported languages in a single line & without ever leaving the code.
Disadvantages of transform
over the code
task:
- Only works for Swift Code. No support for Objective-C. (You can use both methods simultaneously though.)
- Xcode will mark the freshly transformed code as errors (but build will succeed anyways) until next build.
- Not as fast as since SwiftSyntax currently isn't particularly fast. (But this should improve over time!)
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 files you can make it a natural part of your development workflow within Xcode. In order to do this select your target, choose the tab and click the + button on the top left corner of that pane. Select and copy the following into the text box below the of your new run script phase:.strings
Build Phases
New Run Script Phase
Shell: /bin/sh
Next, make sure the BartyCrouch script runs before the steps (and if used) by moving it per drag & drop, for example right after .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 or the shorthand into your value within your base localized Storyboard/XIB file. Alternatively you can add into the field "Comment For Localizer" box in the utilities pane.#bartycrouch-ignore!
#bc-ignore!
#bc-ignore!
This will tell BartyCrouch to ignore this specific view when updating your files..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 in your macros comment part to ignore them so they are not added to your . This might be helpful when you are using a file to handle pluralization (see docs).#bc-ignore!
NSLocalizedString
Localizable.strings
.stringsdict
For example you can do something like this:
The key will be taken from Localizable.stringsdict file, not from Localizable.strings, that's why it should be ignored by BartyCrouch.%d minute(s) ago
Things to Know:
- Files named or files in folders named ".git", "carthage", "pods", "build",
".build" and "docs" (case insensitive) will always be ignored.
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 file which explains your change.CHANGELOG.md
After Release Checklist:
- Run to generate
make portable_zip
.build/release/portable_bartycrouch.zip
- Create new release with text from new section & attach as binary
CHANGELOG.md
portable_bartycrouch.zip
- Run to make a new release known to CocoaPods
pod trunk push
- Update and in , commit & push change
tag
revision
Formula/bartycrouch.rb
- Run
brew bump-formula-pr bartycrouch --tag=<tag> --revision=<revision>
License
This library is released under the MIT License. See LICENSE for details.