Skip to content

How to integrate Nativer SDK

Jump to bottom
Transround edited this page Mar 7, 2015 · 11 revisions

This document describes how to

  • integrate Nativer SDK under Eclipse IDE into your app to get dynamic language resource management capabilities,
  • configure the Nativer Developer Console for managing your app language resources.

Requirements

  • Eclipse with ADT bundle
  • AspectJ plugin
  • Android v7 app compat library
  • Google API (minimum API level 15)

1.How does it work

Nativer SDK uses AspectJ to make the necessary changes in your code instead of you. AspectJ is the Java implementation of Aspect Oriented Programming (AOP). The idea of AOP is to inject code fragments to well-defined places in an application without modifying the source code. AspectJ uses code weaving technology to inject additional code at compile time which means your source code remains intact but your compiled application will contain everything required.

In order to compile code with aspects in Eclipse you need to install the AspectJ Development Tools plugin.

2.General work considerations

In order to avoid disturbing your other projects, or making irreversible damages, we suggest you to create a new, clean workspace, where you will have to import your Android project to.

Import your application project(s) into the newly created Workspace. (File / New / Android project from existing code.). Do not forget to select the “Copy projects into workspace” checkbox, in order to keep your original sources intact.

Check the build target of ALL projects and make sure that you are building with Google APIs, and for at least API level 15.

Make sure that a Java JDK of version 6 is installed.

3.Installing AspectJ

The AspectJ Development Tools is a standard Eclipse plugin which can be downloaded and installed by Eclipse the same way you installed the Android Development Tools.

Select "Help/Install New Software..." in Eclipse and click on Add... The Repository Location depends on which version of Eclipse you use:

Select the newly created update site and check „AspectJ Development Tools (Required)” and „Other AJDT Tools (Optional)” then click on „Next” and follow the directions given by Eclipse.

Notes:

1. Alternatively you can go to http://www.eclipse.org/ajdt/downloads/ to download the AJDT plugin as a zip file and use that as a normal update site.

2. Due to lack of official AspectJ version, the latest Kepler 4.3 release of Eclipse is actually not supported by Nativer. As soon as AspectJ for Kepler becomes available, it will be validated by us, and communicated via our website

4.Converting your Android project to an AspectJ project

In order to tell Eclipse to use the AJDT features in your Android project you must convert it to an AspectJ project. To do so, right click on your project and select „Configure/Convert to AspectJ Project…” from the popup menu.

Note: Don't worry, a project can have multiple natures in Eclipse, so your project keeps its Android nature and you can undo this change easily in the future should you change your mind.

5.Setting up Nativer SDK in your project

Setting up Nativer SDK requires just a little bit more effort than adding an ordinary Android library to your project.

Check out Nativer SDK from Github (https://github.com/Transround/NativerSDK).

Import NativerSDK to Eclipse

Import the NativerSDK project into your workspace.

  • File/Import... and then choose "Existing Android Code Into Workspace". Please do not forget to check the "Copy project into workspace" option.
  • Please note that in case you checked out Nativer SDK into your workspace directly then you have to use File/Import... and then "General/Existing Projects into Workspace"

Set Android Support Library v7 for the SDK and your project

In case you need instructions on how to set library support please see the following link: https://developer.android.com/tools/support-library/setup.html#libs-with-res

Please add Android Support Library v7 to the Android library dependency to Nativer SDK project. (Right click on Nativer SDK project > Properties > Android > Add...)

Do the same procedure for your project.

Add NativerSDK to your Project.

For this, right-click your project, and go to Properties. Select Android on the left of the screen. On the lower part of the screen select Add, and choose NativerSDK from the list. Please be sure you DO NOT CHECK the “Is Library” option. If ready, press OK.

Add NativerSDK project and the nativersdkplugin.jar to your Aspect Path.

Right-click your project and go to Properties. Select AspectJ Build on the left of the screen. Than on the main part of the Properties screen select the Aspect Path tab.

Press the Add Project... button, then select the NativerSDK project and click OK.

Press the Add External JARs button, you will find the nativersdkplugin.jar in NativerSDK project folder. Select this file and press OK. Your Properties screen will look very similar to the picture below. After you added the SDK project and the jar file, press OK to go back to the projects list.

After adding the SDK and the jar to the AspectJ's build path also add them to the Java Build Path.

Please check Order and Export tab of the Java Build Path. Right-click to your project, go to the Properties menu. On the left select Java Build Path, then switch to the Order and Export tab. Please make sure that NativerSDK and the nativersdkplugin.jar are checked, and their order is like in the picture below:

Press OK, then clean the NativerSDK project and your project as well.

For this use the Project / Clean... in the upper menubar of Eclipse for cleaning the SDK and your project. Select Clean projects selected below, check your project and the NativerSDK then press OK.

Declare the Nativer SDK's service in the manifest file in your application:

Copy the following text sequence, and paste it into the AndroidManifest.xml file of your project.

<service android:name="com.transround.plugin.service.PluginInterfaceService" >
    <intent-filter>
        <action android:name="com.transround.tools.PING" />

        <category android:name="com.transround.tools.TRANSLATOR" />
    </intent-filter>
</service>

<activity android:name="com.transround.plugin.activity.RefreshScreen" android:exported="true"/>

Please be careful, and make sure the above text is copied into your manifest file before the </application> closing tag declaration.

Also make sure you do not paste the text inside another application or service, or any other declaration.

Please also make sure you have the following text outside the section:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

6.Protecting parts of your application from the Nativer SDK

If there are some parts of your application which you don't want to be translated for some reason then here is how you can tell Nativer to avoid them.

You can use the ``` @DontTouchThis ``` annotation to tell the SDK which part of your code should be left intact. You can use this annotation on a whole class or on a method. For example if you want a specific Activity not to be modified then you can annotate your Activity class like this:

…
import com.transround.plugin.aspect.TransroundAspect.DontTouchThis;

@DontTouchThis
public class MyProtectedActivity extends Activity {
       @Override
       public void onCreate(Bundle savedInstanceState) {
             super.onCreate(savedInstanceState);
…
       }
}

This way nothing will be affected by the SDK in this Activity.

You can also annotate a method to protect an Adapter for example when you don’t want the data in your Spinner changed:

@DontTouchThis

protected void createMyContents() {

…

     mySpinner.setAdapter(myAdapter);

}

This way myAdapter won't be affected by the plugin but everything else will be.

 

7. Configure the Nativer Developer Console.

In order to utilize the dynamic language resource management capabilities you need to register and configure your app in the Nativer Management Console:

Once you finish with the setup on the management console, the backend will generate the test language resource file - so you can check easily the scope of dynamic resource management.

Glossary

Host Application: Is the original Application of a developer. The App Localization Demo (https://github.com/Transround/LocalizationDemoDev) is an example of a host application. By adding the Nativer SDK to it, becomes NLE (Nativer Localization Enabled) Application

NLE Application: Stands for Nativer Localization Enabled Application. This is an original Application of a developer, in which the Nativer SDK has been embedded.

Nativer SDK: A set of functions and libraries, which enable the host Application to become easily translatable in the Nativer Ecosystem

Nativer Application: This is Transround’s own application, called Nativer, which implements majority of the functionality of the Nativer Ecosystem, like requesting localizations, downloading ready localizations, translate, proof reading, support, etc.

Clone this wiki locally