Author's note: Thanks everyone for making Laurine the TOP trending Swift repository in the world - this is amazing and very heart-warming! But this is just the beginning.
For the last few years, my team and I worked on a tool to completely change mobile programming - make it way faster and more fun for everyone - and we are nearly ready to release it to the world. If you are interested, head over to Product Hunt and check it out!
Localization code generator written (with love) for Swift, intended to end the constant problems that localizations present developers.
Too tired to read? That is understandable. That is why I made this example. You will find it little bit different from what you usually see - check it out. Just download and run in Xcode.
Latest version of laurine now supports Swift 3.2 / 4.0 and higher (XCode 9). Looking for version compatible with XCode 8? We have that as well - switch to S3 branch. Looking for version compatible with Swift 2? Here you go - switch to S2 branch.
Laurine is a clever Swift script that scans your localization file and generates structured, high-performance code out of it (in both ObjC or Swift, your call), thereby making the usage of localization strings much easier and safer.
The great thing is that by removing magical strings from your code, the compiler can actually tell you when you forget to make changes (and where), if your localization file changes. It also introduces type checking for strings that contain runtime format specifiers (%@, %d etc.).
Laurine requires Swift to run and can be used from the command line as well as from a build script (recommended). Laurine uses CommandLine to parse command line arguemnts: no extra configuration is needed.
Once you run Laurine, the output will be one .swift or .m file containing a Localizations structure / object. From this single access point, you will get access to all the sweetness:
Variables
For each string that does not contain any special characters, a property is generated. For example:
"PROFILE_PHONE_NUMBER" = "Your phone number!"can be then used like this:
self.labelToLocalize.text = Localizations.ProfilePhoneNumberin Xcode, autocomplete is actually, for once, really helpful! Madness.
Methods
If your localization string has runtime format specifiers, it is generated as a method instead. Laurine detects the format specifiers and generates a proper method header from that definition. There is no limit to how many of them you have.
For example:
"PROFILE_INFO" = "I am %@, I am %d years old and %.2fm in height!"can be then used like this:
self.labelToLocalize.text = Localizations.ProfileInfo("Jiri", 25, 1.75)Once again, Xcode autocomplete for the win! Insanity.
Swift support
Swift-written application is recommended Laurine usecase. Internally, it uses nested structures to make your life much easier. Also, it is extremely performant and will have no impact on your current codebase.
ObjC support
Objective-C is supported from v0.2 as well. Because of the way the code is generated, you can write just the same code as you would in Swift, using dot notation to access each next element. For example:
NSString *text = Localizations.ProfileInfo("Jiri", 25, 1.75)This produces exactly the same result as you would get in Swift and is recommended.
It is best practice to make the keys as descriptive and structured as possible. Laurine takes advantage of that to generate nested structures rather than overly long key names. For example:
"PROFILE-NAVIGATION_BAR-ITEMS-DONE" = "Done" // -c -d -
"PROFILE.NAVIGATION_BAR.ITEMS.DONE" = "Done" // -c -d .Is actually converted to:
self.labelToLocalize.text = Localizations.Profile.NavigationBar.Items.DoneThis way, you can easily traverse through thousands of strings without even thinking about it (obviously, how you actually group your strings is up to you).
You can use -d "delimiter" option to specify which character you would like to use for nesting, defaults to - (slash).
Use _ (underscore) to make camel case strings (MY_AWESOME_WORD to MyAwesomeKey), or omit "c" option to disable this feature.
Note: Language-specific keywords (such as Swift: func and ObjC: YES) and names starting with numbers (Profile.1stButton) will get prefixed with _ to prevent build errors.
Laurine uses script parameters to change the way how output is generated. Currently, the following is supported:
-i, --input:
Required | String | Path to the localization file
-o, --output:
Optional | String | Path to output file (.swift or .m, depending on your configuration. If you are using ObjC, header will be created on that location. If ommited, output will be sent to stdout instead.
-l, --language:
Optional | String | [swift | objc] | Specifies language of generated output files | Defaults to [swift]
-d, --delimiter:
Optional | String | String delimiter to separate segments of each string | Defaults to [.]
-c, --capitalize:
Optional | Bool | When enabled, name of all structures / methods / properties are automatically CamelCased | Defaults to false
Command line
If you wish to generate output just once, run following from terminal in the directory where you have the script downloaded:
$ swift LaurineGenerator.swift -i Localizable.strings -c -o Localizations.swift
or for ObjC
$ swift LaurineGenerator.swift -i Localizable.strings -c -o Localizations.m -l objc
or, alternatively, if you downloaded it through Brew:
$ LaurineGenerator.swift -i Localizable.strings -c -o Localizations.swift
or for ObjC
$ LaurineGenerator.swift -i Localizable.strings -c -o Localizations.m -l objc
Build script
The recommended way to use Laurine is to create a "Run Script" Build Phase (Xcode > Project > Targets > Your build target > Build Phases > New Run Script Phase). This way, Laurine will be executed before each build and will ensure the integrity of your translations. Be sure to put the script before the "Compile Sources" phase, as it has to generate the code first, before it can be used anywhere else. For convenience, you can just copy the following, and change the configuration appropriately.
set -x
# Get base path to project
BASE_PATH="$PROJECT_DIR/$PROJECT_NAME"
#--------- START OF YOUR CONFIGURATION (change Path_To_.. to fit)
# Get path to Laurine Generator script
LAURINE_PATH="$BASE_PATH/Path_To_Generator/LaurineGenerator.swift"
# Get path to main localization file (usually english).
SOURCE_PATH="$BASE_PATH/Path_To_Base_Localization/Localizable.strings"
# Get path to output. If you use ObjC version of output, set implementation file (.m), as header will be generated automatically
OUTPUT_PATH="$BASE_PATH/Path_To_Output/Localizations.swift"
#--------- END OF YOUR CONFIGURATION
# Add permission to generator for script execution
chmod 755 "$LAURINE_PATH"
# Actually generate output. -- CUSTOMIZE -- parameters to your needs (see documentation).
# Will only re-generate script if something changed
if [ "$OUTPUT_PATH" -ot "$SOURCE_PATH" ]; then
"$LAURINE_PATH" -i "$SOURCE_PATH" -o "$OUTPUT_PATH"
fi
Brew
Laurine does not require installation. For your convenience, you can make it easily accessible from /usr/local/bin by installing Laurine through brew:
$ brew tap jiritrecak/laurine
$ brew install jiritrecak/laurine/laurine
Now you can just run it from everywhere:
$ LaurineGenerator.swift ...
GIT
You can also just clone it wherever you desire:
$ git clone https://github.com/JiriTrecak/Laurine.git
$ sudo cp laurine.swift /usr/local/bin/laurine.swift
Download!
Yes, you can just download the script itself from this repository, it does not need anything else.
Laurine should suit most of developers, because it covers all the basic stuff. That being said, there are still things missing to have full coverage of what localizations have to offer. Here is the full list of features that will Laurine contain once it is complete:
- Basic localization strings to variables
- Complex localization strings to methods
- Multilevel structures (nesting)
- Generate Swift output
- Generate ObjC output
- Support for all special localization characters
- Localization Tables
- Plural support
- Gender support
- Tool for automatic replacement of NSLocalizationString in project (thanks @Vaberer )
I will gladly accept Pull Requests (and I encourage you to do so). If you encounter any bug or you have enhancement that you would like to see, please open an issue. Please make sure you target your PR against Development branch.
I'd also like to make round of applause to Marcin Krzyżanowski for his Natalie Generator, which heavily inspired this project by his approach. Hope we meet for beer one day!
If you liked it, check out my other library - Warp, that will help you with development of your data models.
Or, if you would like to know me better, check out my portfolio.
##Licence
The MIT License (MIT)
Copyright (c) 2015 Jiří Třečák
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.