Automating iTunes Connect deployment with Fastlane and Lokalise

Can you manage your iOS app’s metadata in iTunes Connect? It’s trickier than you think.

Metadata are sections about your app: name, description and what’s new.

At first, managing metadata is easy: you update one text file and copy its contents into iTunes. But time goes by and your app grows. You support more markets and localize into more languages. You now have 10, 20, 30 files, often full of characters that you can’t even read. Updating them all like you used to becomes a hassle. Repeat this with a couple more apps, and it becomes a nightmare.

Every global app reaches a point when it takes too much time to update its description and what’s new sections manually. The more metadata you manage, the more time it takes.

You can manage metadata faster and update it automatically with Fastlane and Lokalise.

Here’s how to automate iOS metadata updates:

• Setup. Create an empty Lokalise project and application in iTunes Connect.
• Prepare supporting programs:
  • Fastlane. Set up Fastlane to automate your updates.
  • Deliver. Use Deliver to download metadata.
  • iTunes Connect. Align your metadata with iTunes Connect language support.
• Import metadata to Lokalise. Download and use Lokalise Fastlane actions.
• Manage metadata. Update metadata in Lokalise.
• Release metadata to the public. Automatically update metadata in iTunes Connect.

Setup

1. Open a new Lokalise project. Our example uses English as the default language and doesn’t contain any language keys yet.

2. Create an application in iTunes Connect. Note that languages in iTunes Connect are independent of the languages your app is localized to.

Our example has English (U.S.) as the primary language and English (U.K) as the supported language.

English (U.S) has data in name, subtitle, promotional text, description and keywords fields.

English (U.K) only has data in the name field.

Fastlane

Fastlane is a collection of tools for iOS (and Android) that developers use to automate tedious tasks like generating screenshots, dealing with provisioning profiles, and releasing your application.

1. To get Fastlane, run this script in your terminal:

gem install fastlane -N

This installs the complete Fastlane toolchain without documentation (saves time, space and nobody reads it anyway).

2. To set up Fastlane, go to your project root folder and create fastlane directory and Fastfile:

cd path/to/your/project
mkdir fastlane
touch fastlane/Fastfile

This is enough for what we are going to do. For you application, you might want to run a full initialisation process (more details here). Fastfile contains a list of actions that can be performed by calling them using Terminal.  You can find a simple Fastfile generator here. We also explain how to generate relevant Fastfiles in this tutorial.

Deliver

Deliver is a tool included in Fastlane.

Deliver can upload and download screenshots, metadata (keywords, description, what’s new and other) and binaries to and from iTunes Connect. We will use it for metadata.

1. To see how Deliver works, download your current metadata with this command:

fastlane deliver init

This creates a Deliverfile in fastlane directory and fastlane/metadata directory with current metadata.

When you open fastlane/metadata you can see a couple of directories and a bunch of files in them. Each language has its own folder and each metadata field has its own .txt file.

Deliver uses the same directory and file structure to update data in iTunes Connect. It will override metadata in iTunes Connect if it finds a new .txt for the same metadata field.

Keep in mind: if your most recent .txt file is empty, it will clear your metadata in iTunes Connect.

2. To download the latest metadata from iTunes Connect, run this command:

fastlane deliver download_metadata

iTunes Connect

iTunes Connect supports multiple English regions. By default, any region that doesn’t have its own metadata filled in will see your English (United States) (en-US) metadata. This also means there’s no English (en):  and if you want translate metadata for German users you would normally need to use German (Germany) (de-DE) language instead of German (de). To help you with this, our script automatically maps these two languages:

• en-US to en
• de-DE to de

Other languages are left as they are. You can find a list of all languages supported by iTunes Connect here.

Import metadata to Lokalise

1. Download Lokalise Fastlane actions from GitHub here. Store them into fastlane/actions directory.
2. Create a lane. Lane is an executable command in Fastlane that you write to perform certain actions. To create a lane that will import metadata to Lokalise, add this code into your Fastfile located in fastlane directory:

lane :update_lokalise_itunes do
  lokalise_metadata(
      api_token: "<your_token>",
      project_identifier: "<your_project_identifer>",
      action: "update_lokalise_itunes",
      add_languages: true,
      override_translation: true
  )
end

This lane will read metadata that Deliver has downloaded, create languages, add keys and their translations to your project in Lokalise.

3. Run the lane to import metadata to Lokalise:

fastlane update_lokalise_itunes

Note: You can read about all available parameters and their functions in README or by running this command:

fastlane action lokalise_metadata

Manage metadata

Now try to manage iTunes Connect metadata in Lokalise:

1. Update promotional text and keywords for English (U.S) (en in Lokalise) and English (U.K.) (en-UK) languages.
2. Copy description for English (U.S) to English (U.K) and change localization to localisation.
3. Leave name and subtitle as they are.

Update metadata in iTunes Connect

1. Add this lane to your Fastfile.

lane :update_itunes do
   lokalise_metadata(
      api_token: "<your_token>",
      project_identifier: "<your_project_identifer>",
      action: "update_itunes"
   )
end

2. Run it:

fastlane update_itunes

3. It’s done! Your iTunes Connect metadata should now be updated and look like this:

English (U.S)

English (U.K)

Want to learn how to get started with iOS localization? See our comprehensive tutorial.