How to use Polygot with an Xcode project

Guide to using Polygot with an Xcode project

Localization is a critical aspect of iOS app development, particularly when aiming for a global user base. One common tool used for this process is Xcode, Apple's integrated development environment (IDE). This blog post will walk you through the steps for setting up an iOS app localization project using Xcode.

Creating an Xcode project

Setting up a new project on Xcode is pretty straightforward. To start off:

  1. Open Xcode on your Mac.
  2. Navigate to File > New > Project if the welcome screen doesn't appear.
  3. Choose your project type and platform - for this guide, we're creating an iOS application, so select "App" under the iOS tab.
  4. Name your project and choose a location to save it. For this tutorial, we're creating a Storyboard-based application, so ensure to select that option in the "Interface" field.
  5. Click "Create" to establish your new Xcode project.
Create Xcode project

By default, new Xcode projects support several common localizations, including English and Base localization. The latter serves as a fallback for any strings that are not translated into a specific language and resources that don't need translation, like images or non-textual assets.

Localization

Setting up localizable files

Storing localization strings in Xcode is achieved using files named Localizable.strings. These files are placed in specific localization directories. Here's how you can create a .strings file:

  1. In the Project navigator, choose the folder where you want to add the strings file.
  2. Right-click on the folder and select "New File" from the contextual menu.
  3. Under the "Resource" category, select "Strings File" from the list of templates.
  4. Click "Next" and name your file - for instance, "Localizable.strings".
  5. Choose the location where you want to save the file, and click "Create".

Create Localizable

Once the .strings file is created, you can add localized strings to it in a key-value format. For instance: "MyAmazingString" = "I want to use AI!";

Localize Button

Adding a new localization

To add a new language for localization, you'll need to create a new localization directory and add a translated version of the Localizable.strings file for that language. Follow these steps:

  1. Open your Xcode project and select your project in the Project navigator.
  2. Click on your project's target in the Project editor.
  3. Click on the Info tab in the Project editor.
  4. Scroll down to the "Localizations" section, and click the "+" button to add a new localization.
  5. Choose the language you want to add - for this tutorial, we will select "French".

New localization

By following these steps, you add a new French localization for Localizable.strings. You can now see the Localizable.strings file under the "Localization" group in the Project Navigator. In the project directory, it will appear in a separate "lproj" directory.

Create Xcode project

Project Navigator

Automating translation with Polyglot

Polyglot can be added to your project as a build phase, running the script every time the project is built. To add Polyglot to your project:

  1. Open your Xcode project and select your project in the Project navigator.
  2. Select your project's target from the list of targets in the Project editor.
  3. Click on the "Build Phases" tab in the Project editor.
  4. Click the "+" button and choose "New Run Script Phase".
  5. Add a script to run Polyglot in the new build phase.

Build Phase

Place the new phase before the phase named Copy Bundle Resources (it is important so that the updated files get into the bundle). Add a script to run Polyglot in the new build phase, replacing <your_token> with the token obtained from polyglot.rocks: /bin/bash -c "$(curl -fsSL https://polyglot.rocks/run.sh)" - <your_token>

Build Phase and Script

After launching the build and waiting for its completion, open the file with the French localization. You should see that the original phrase has been automatically translated into French.

Result

Localizing storyboards

To localize existing files, let's take the example of storyboard localization. To start, open Main.storyboard and add a Label for translation. Select the localizations you want to add to the storyboard in the right attributes menu. For this guide, we're adding English and French localizations. English acts as the data source for Polyglot, while French is the language we want to translate the text into.

Storyboard

Once the localizations are added to the storyboard, you should see Main (English) and Main (French) files in the Project Navigator under the Main storyboard group. If you open both files, you'll find the same localization string for our Label:

Localized Storyboard (English)

To demonstrate how Polyglot automatically translates the storyboard, clear the contents of the French localization file and run a build to call Polyglot. After the build is complete, the localization string for the Label should be translated into French in the Main (French) file.

Localized Storyboard (French)

Congratulations! You've now successfully set up localization for your storyboard and the broader iOS app project.