Setting up Respresso in an iOS project

To get started, you need a project in Respresso.
Respresso projects' are designed to be shared across platforms. If your app is implemented for Android or Web you can use their Respresso project.

Set up a new iOS project

  1. Install the Respresso CLI on all the machines you want to use to sync resource files.
  2. Go to the project dashboard in Respresso and find your project token at the top.
  3. In your project/module directory, run respresso init --token <your project token>. This will automatically create the respresso.json config file based on your project structure. The CLI tries its best to guess your project config, but you might need to customize it manually as iOS project structure changes dramatically from team to team. The respresso.json file should be added to your VCS (aka. Git).
  4. Run respresso sync. This will create the respresso.lock file and download/upload all the requested resource files. For VCS include or ignore dilemmas, see the get started page of the Respresso CLI.
  5. Drag the new files / folders to the Xcode's project navigator from Finder. (The CLI will list them after the sync.) Make sure you use the Create groups option for folders in Xcode.
  6. Optionally, add the following Run Script to your target in Xcode immediately after the Dependencies Build Phase to execute the sync before each build:
respresso sync

For other Xcode setups, see the iOS Xcode Sync page

The Respresso CLI is highly customizable. You can learn more about it in the get started page of the CLI. If you have a lots of images, colors or other resource files, you may need to use the --no-file-locking flag to avoid a limitation of MacOS.

Available categories and groups

All resource categories in Respresso are supported for iOS. This includes localizations, images, colors, app icons, fonts and raw configs.

Resource files are usually placed in the ios sync group that are necessary for you project. These include iOS specific formats of your localizations, color, images etc.

In addition to your resource files, Respresso provides typo-safe utility classes for localizations and colors. These classes come in two languages: Objective-C in the objc group, Swift in the swift group. These sync groups are optional, you can choose not to use any of them or pick the one that matches your project's main programming language.

Accessing localizations

Respresso provides typo-safe RespressoStrings helper class with read-only properties - and functions for localizations with variables - to improve your productivity. This class should be used each time you want to access localizations handled by Respresso. For more info see the localization helper classes in Swift and Objective-C

Migrate an existing iOS app

  1. Go to your Respresso project and import your resource files in each resource category.
  • Localization: Go to the localization category and import your localizations.
    1. You will need to add a default language. It should be the one you set as the app language in Xcode or the language in your Base.lproj/Localizable.strings localizations file.
    2. Drag and drop your default Localizable.strings file or select it using the Import button. All settings will be fine, just press the Import button.
    3. If you have multiple languages, you need to add them using the Language Management Toolbar
    4. Import each language one by one, by selecting the language from the toolbar, them importing it. Make sure you import it to the proper language! (The localization file is usually placed in <language code>.lproj/Localizable.strings)
  • Images: Go to the image category and import your icons and images.
    • Drag and drop your Assets or Images.xcassets directory (or the one you used to store your image assets) or select it with Upload button. You might get some errors for non image files, like Contents.json files. You can ignore them.
    • If you uploaded raster images (png, jpg) you will need to keep only the largest resolution and remove the other ones. You will also need to remove the @3x from the key.
    • Once you uploaded the images and removed the unnecessary ones, you need to press the Save button. The first save will take a while. If you added more than 10 images, it may show an Unknown error due to a timeout, but the save will eventually finish in the background. Just come back in a few minutes and refresh the page.
  • Colors: Go to the color category and import your colors. To do so, zip your Colors.xcassets folder. Then drag and drop the zip archive or select it using the Import button.
  • App icons: Go to the App icon category. Upload your app icon to the single image section. Don't forget to press the Save button at the bottom of the page. (If your Respresso project will be used on Android, ask an Android dev to set up a dynamic icon instead of uploading the single layer one.)
  1. Set up your project as you would with a new project. Instructions above.
  2. When you run your first respresso sync you might need to confirm some file overrides. For this reason, you must run the first sync from a terminal and not from Xcode.
  3. After your sync finishes, you will need to use the RespressoStrings helper class to access localizations instead of the NSLocalizedString calls. Alternatively, you can configure the CLI to override your Localizable.strings files instead of creating a new table.
  4. Hurray! Your project is good to go. If you change something in Respresso and run a sync, it will magically appear in your project.

Keep in mind, that importing the same resources from multiple platforms may cause unexpected behaviour. Imports merge the imported resources with the existing ones. (Usually overriding the pre-existing ones.) If you import your iOS resources then import the same ones from your Android project will result in a mixture or the resources unless you named them exactly the same. In that case, the Android version will be used as it was imported later.

Skip the usage of Localization helper classes

As localizations are placed in a Respresso specific directory and table named RespressoStrings, accessing them requires a few extra parameters when using the NSLocalizedString. This is included in the RespressoStrings helper class, but you can choose to skip the usage of Respresso's utility classes.

To do so, you have three options:

  1. Properly parametrize NSLocalizedString each time you use it. Something like NSLocalizedString("your key goes here", tableName: "RespressoStrings", bundle: Bundle.main, comment: "")
  2. Configure a target override in the CLI config to override your default Localizable.strings files. (This will break the utility class, but you don't want to use it anyway.)
  3. Change the processor configs in the Respresso Flow. (This requires understanding of the Respresso Flow. For assistance, contact us at info@respresso.io.)

If you want to completely get rid of the helper classes, you will have to remove the corresponding objc or swift group from your resources array in the respresso.json config.