[Nexus One Android Development] djmcnz:
[HOW TO] Create a MIUI Language Pack

Okay guys, there's a lot of demand for this rom and for language packs but not yet a lot of people who know how to make the packs. Whilst I set up the crowdin translation project I can not create or maintain language packs.

So, here's a summary of the instructions required to create a language pack for MIUI (indeed for any app/rom). You need a collection of tools and a little patience but the process isn't too difficult so do give it a go.

Also note that this summary includes generalisations for brevity. These instructions assume you have a deodexed rom.

Introduction

For the purposes of this post language information is stored in XML strings in files on the Android system. In the case of MIUI and these instructions we will be dealing with .apk files (applications).

Within the apk files is a resources directory (/res) and within this are various values directories, there is a default values directory (/res/values) and alternative language values directories (e.g. /res/values-DE and /res/values-IT).

If the rom is set to use it's default language it will read values from /res/values although these may NOT be in English. In MIUI, all of the common Android ASOP values in /res/values are English but the (additional) custom MIUI strings are in Simplified Chinese.

If you select a different language in the ROM than the default then the appropriate values directory will be searched. If a suitable string that matches your language selection is found in the alternative /res/values-xx directory then that string will be used instead. If an alternative does not exist then the default will be used.

Example:

/res/[COLOR="red"]values[/COLOR]/strings.xml
<stop_button_text>[COLOR="Red"]Stop[/COLOR]</stop_button_text>

/res/[COLOR="red"]values-DE[/COLOR]/strings.xml
<stop_button_text>[COLOR="red"]Halt[/COLOR]</stop_button_text>

/res/[COLOR="red"]values-IT[/COLOR]/strings.xml
<stop_button_text>[COLOR="red"]Basta[/COLOR]</stop_button_text>

In this example, if the language is set to the default the word "Stop" will be used, if it is set to German the word "Halt" will be substituted in, likewise "Basta" for Italian.

So, to add languages to a rom (or app) or to make an app multi-lingual you need to either change the default strings in /res/values/strings.xml to the ones you want to use or, and this is the preferable approach, add a /res/values-xx/strings.xml with the translations you want. The first approach will work (changing the default strings) but is not recommended because the Android Open Source Project and Android development in general, defaults to English. It's best to use the built in language substitution capabilities of Android rather than to work around them. Indeed, if the MIUI devs actually added their strings in English to /res/values/strings.xml and the Chinese equivalents in the appropriate directory this rom would already be in English!

Adding Languages

To add a translation file (strings.xml) to an apk you need to:

decode the apk

create a language directory

add the translation files

recompile the strings

add the new strings to the apk

Which all sounds a little daunting but it's really quite straight-forward, rewarding when you see the result and a good way to understand how parts of Android work. Here's how you can do it.

1. decode the apk

You will need the excellent apktool from brut.all which you can get from the link below. apktool is relatively easy to use but includes some little tricks so you will need to read the wiki and thread about it.

Do NOT just post problems about apktool if you can't get it to work. The tool DOES work so if it's not decoding (or encoding) your apps correctly then you're probably doing something wrong. If you start with this understand BEFORE you ask for support you'll get a lot more help... :)

apktool: http://code.google.com/p/android-apktool/

wiki: http://code.google.com/p/android-apktool/w/list

thread: http://xdaforums.com/showthread.php?t=640592

Please make sure you run the following command to include the MIUI framework in apktool. You only need to do this once for each framework. If apktool works with one rom and not the next then (re)install the framework for that rom.

apktool if framework-res.apk

Where framework-res.apk is the one from the rom you are working with. Make sure apktool can find (the correct) framework-res.apk before you run this command.

This thread is not for apktool support.

Now, before you proceed, decode a simple app from MIUI (such as updater.apk) using apktool, do not make ANY changes, then re-encode it using apktool. For example:

apktool d Updater.apk ./decoded/
apktool b ./decoded/ new_updater.apk

Use the -v (verbose) flag in apktool if you have problems and need to diagnose further.

Remember, Android uses a case-sensitive file system, make sure your capitalisation is correct.

Typically you will not be able to install this apk because it is not signed so if you want to test the process further you can now just try step 5 below using the two apks you have.​

2. create a language directory

Assuming you can decode/encode now, this is the easy bit. For your decoded app, navigate to the directory it was decoded in, then to the /res/ directory and simply create an empty directory for your language (e.g. /values-FR/) - use international naming conventions.
​

3. add the translation files

Again, not too difficult this. Download the appropriate language file for your apk from the crowdin project linked below and, using the same structure as exists in /res/values/strings.xml create a new file called strings.xml in your alternative language directory (e.g. /res/values-ES/strings.xml).

The news strings.xml may contain as many or as few translations as you like. Remember, if a translation does not exist the default value from /res/values/strings.xml will be used.

Crowdin: http://crowdin.net/project/miui-rom-translation/invite

The xml formatting and tag names need to match exactly with the default strings.xml in /res/values although the translated file does NOT need to be complete.

It is worth remembering here that unless your source apk is already translated to English then some of the default values in /res/values/strings.xml will still be in Chinese, it would pay to check these.​

4. recompile the strings

Now, if you've done everything carefully and correctly this step is really easy, all you need to do is recompile the apk with apktool using the b (for Build) switch.

apktool b ./<decoded_apk_dir>/ <output_apk_name>.apk

If this throws errors or does not work then use the -v switch to turn on verbose mode and diagnose your problem. If you did the test in step #1 and it worked then any problem at this step is likely related to your news strings.xml. Back out the changes one by one until you have found the problem and try again.

If you simply can't get it to compile with your changes then try just making a single change to the default strings.xml file in /res/values and see if that works for you.

Do NOT sign the apk!​

5. add the new strings to the apk

Easy. Open your new apk with a zip program (like 7Zip for Windows) and copy out the resources.arsc file in the root directory of the apk. Now take that file and copy it into the source apk from the rom overwriting the existing one. This process replaces the strings but keeps the integrity of the signatures on the files.

You can now push the modified file to your phone, replacing the stock one, reboot and you're translated. Push the file using "adb push" or copy it into place using a root file manager, do not "install" the new apk. Make sure you put it in the correct place (replace the original) and reboot.​

Conclusion

This process will help you add languages to any app including those in the MIUI rom. Because it's a rom the strings are contained in many different apps as well as framework-res.apk. To completely translate the rom you will need to edit every apk that has strings in it.

You will need to do this every time an apk in the rom changes. If a new version is released and say launcher2.apk is changed but updater.apk is not, then you can retain your updater.apk but you'll need to re-edit your launcher2.apk.

When an app changes the default strings.xml may also change. In this case you will need to make corresponding changes to your translations.

Good luck and if you get really stuck there's lots of people in this that have achieved success and may be willing to help!