Installing third-party dictionaries for built-in iOS Dictionary.app with Ansible

Abstract

In my daily work and entertainment I use several iOS devices. The large part of the content which I consume is written in English. In order to improve my English skills I try to translate the most new words. iOS supports words translation with its built-in Dictionary.app. As of iOS8 its imposible to add a third-party dictionary to a non-jailbroken iOS. Apple permits the user only to download a dictionary from their registry. Currently there is only one approach to add the custom dictionary — by replacing the content of the existing one, which was previously downloaded from Apple registry.

Following instructions describe the process:

1. Download the dictionary, which content will be replaced, from Apple registry via iOS tooltip > Define > Manage.
2. Find the AssetData/Content folder with the content of the downloaded dictionary under /var/mobile/Library/Assets/com_apple_MobileAsset_DictionaryServices.dictionary2/
3. Replace the folder by the third-party dictionary content folder Third-PartyDictionary.dictionary/Content

If iOS has not enough disk space it can remove downloaded dictionaries without user permissions. They can also disappear after iOS upgrade. Therefore it is worth to automate the process of adding new dictionaries/installing iOS tweaks in order to make the upgrade process of jailbroken iOS less painful.

Objective

Automatically restore iOS tweaks and applications from Cydia on the jailbroken iOS after upgrade

Requirements

• One-Click deployment
• Multiple tweaks support
• As few GUI actions on iOS as possible
• Short time to market (TTM)

Alternative evaluation

Let us to study possible alternatives with the case of adding third-party dictionaries:

via Cydia package

• no desktop for installation required
• no SSH setup required
• could be done anywhere
• repository hosting
• complicated packaging and testing
• WiFi for installation required

via Ansible

• fast packaging
• reusable knowledge
• One-Click restore of the entire configuration
• desktop with Ansible and git required
• SSH on iPhone required

The implementation of the Cydia package is more time-consuming and doesn't supports the One-Click restore, therefore it is less attractive. Restoring with Ansible has an issue, which makes it impossible to add dictionaries under certain circumstances. It requires the desktop with Ansible and git installed. Nevertheless the small probability (e.g. vacation, under way) and slight negative effects (e.g. unable to translate an unknown word) make it possible to ignore the issue.

Implementation

Jailbroken iOS is more or less an unix OS. Cydia brings apt-get package manager, which makes it possible to install SSH server and python required by Ansible. The lack of Ansible support for iOS in obtaining of OS facts could be solved by adding gather_facts: no to the - hosts configuration. The rest of the process declaration for Ansible is pretty simple and OS independent. The only thing you should take in account is the limited selection of the packages could be installed by apt-get.

The magic playbook:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

- name: Downloading dictionaries to be installed
  local_action: get_url url={{ dict_archive[item].url }} dest={{ role_path }}/files/{{item}}.zip
  with_items: dictionaries

- name: Unarchiving dictionaries to be installed
  local_action: unarchive src={{ role_path }}/files/{{item}}.zip dest={{ role_path }}/files/
  with_items: dictionaries

- name: Looking for target dictionaries locations on iOS
  shell: find {{ target_dir }} -name {{ dict_archive[item].target_dict }}
  register: target_dict_paths
  with_items: dictionaries

- fail: msg="The dictionary '{{ item.cmd | regex_replace("find .* -name ", "")}}' was not found on iOS. Perpaps you forgot to download it over iOS tooltip > Define > Manage."
  when: item.stdout is undefined
        or
        item.stdout is none
        or
        item.stdout | trim == ''
  with_items: target_dict_paths.results

- name: Removing the content of target dictionaries on iOS
  file: path="{{ item.stdout }}/Contents" state=absent
  with_items: target_dict_paths.results

- name: Coping the content of source dictionaries to target dictionaries on iOS
  copy: src={{ role_path }}/files/{{ item.item }}.dictionary/Contents dest={{item.stdout}} directory_mode=0755 mode=0644 owner=mobile group=mobile
  with_items: target_dict_paths.results

You can also take a look at the entire Ansible role to download and add third-party dictionaries on iOS on Github.