IOS Quick Start

This guide provides a step by step tutorial on how to integrate the Translation Exchange SDK with your IOS mobile applications and allow you to translate your app into multiple languages.

Before Getting Started

Make sure you have a Translation Exchange account, and have created a project in your dashboard.

Requirements

  • iOS 8
  • CocoaPods

1. Installation

To install the SDK through CocoaPods, simply add the following line to your Podfile:

pod "TMLKit"  

and run

pod install  

Alternatively, you can clone this repository:

$ git clone https://github.com/translationexchange/tml-objc.git
$ cd tml-objc/TMLKit
$ pod install

Then build TMLKit.xcworkspace and simply include the build framework in your project.

You can also drag TMLKit.xcodeproj into your application's Xcode project and have it configured as a linked framework.

Please do note, that if you're building TMLKit as a library - you're using TMLKit.xcworkspace, as the project references CocoaPods that provide auxiliary support), whereas when you're including TMLKit in your application's project as a linked framework, you're using TMLKit.xcodeproj.

2. Configure the SDK

You would need to configure TMLKit in your main.m file like this:

#import <TMLKit/TMLKit.h>

int main(int argc, char * argv[])  
{
    @autoreleasepool {

        [TML sharedInstanceWithApplicationKey:@"<APPLICATION KEY>" accessToken:@"<ACCESS TOKEN>"];
// ...
        return UIApplicationMain(argc, argv, nil, NSStringFromClass([AppDelegate class]));
    }
}

Please note, if you decide to configure TMLKit at a later phase, for example, in your App Delegate, when responding to UIApplicationDidFinishLaunchingWithOptions - TMLKit won't be able to automatically localize strings found in your Interface Builder (xib) files, as they get processed before any application level notifications are dispatched.

Application Key is required for TMLKit to function. Access Token is only required for the Translation Mode, which enables you to localized your application at run time. While it's a very helpful feature, you don't want to inadvertently release your application configured with an access token. One way to deal with this is:

 #if DEBUG
 [TML sharedInstanceWithApplicationKey:@"<APPLICATION KEY>" accessToken:@"<ACCESS TOKEN>"];
 #else
 [TML sharedInstanceWithApplicationKey:@"<APPLICATION KEY>" accessToken:nil];
 #endif

This way developers and translators can utilize Translation Mode, while released applications leave the feature out.

You would need to include TMLKit.h whenever you use TMLKit. It may be less cumbersome to add it to your project's Prefix Header file and not worry about including it in individual files.

 #import <TMLKit/TMLKit.h>

TMLKit comes with a variety of macros to help with localization. TMLLocalizedString() should be familiar to you if you've used NSLocalizedString() before. In fact, if your project is already using NSLocalizedString, you can simply import TMLKit's redefined macros:

 #import <TMLKit/TMLKit+NSLocalizedString.h>

However, you only get full use of TML via TMLLocalizedString() macros. TML supports default inflectors, pluralizers, contextualizer and language cases, which to better code and much better localization.

3. Wrapping Strings

TMLKit comes with a variety of macros to help with localization:
* TMLLocalizedString() - should be familiar to you if you've used NSLocalizedString() before. * TMLLocalizedAttributedString() - is similar to TMLLocalizedString but returns an NSAttributedString. * TMLLocalizedDate() and TMLLocalizedAttributedDate() - are special case functions that format dates.

Here are some examples:

TMLLocalizedString(@"Hello World");  
// "Hello World"

TMLLocalizedString(@"You have {count || message}", @{@"count": @5});  
// You have 5 messages

TMLLocalizedAttributedString(@"{user} sent {target} [bold: {count || gift}]", @{@"user": currentUser, @"target": targetUser, @"count": @5);  
// Michael sent Anna 5 **gifts**

Learn more about marking up your content in the IOS Integration section of the docs

5. Activate Translation Mode

Once your application is running, you can start using translation mode. To activate translation mode, use a four-finger long-press gesture. The screen will flash white indicating translation mode is enabled. Subsequent invocations of the same gesture will present some options as well as a way to disable translation mode.

While in translation mode, use single finger long press gesture over text to bring up Translator Controller, which allows you to translate, change and manage existing translations of that string.

You can provide your own gesture recognizer for invoking translation mode. Say, in your AppDelegate.m:

@interface AppDelegate()<TMLDelegate>
@end

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    TML *tml = [TML sharedInstance];
    tml.delegate = self;
}

- (UIGestureRecognizer *)gestureRecognizerForInlineTranslation {
  // return your own instance.
}