azooKey: a Swift Japanese keyboard with its own conversion engine

What azooKey puts under the iOS keyboard

azooKey is a Japanese keyboard application for iOS and iPadOS. The description in the repository summary calls it an open-source Japanese keyboard for iPhone and iPad, written in Swift, powered by its own kana-kanji conversion engine, offering live conversion, flexible key layouts and a SwiftUI interface.

The interesting part for a developer is that this is a complete input method rather than a layout pack. A Japanese keyboard on iOS has to do two things: produce kana from key presses, and convert a kana sequence into kanji. The second half is where most of the difficulty sits, because Japanese input has no spaces, so the engine must guess where one word ends and the next begins. azooKey bundles its own answer to that problem instead of deferring to the system input method.

That choice shapes the codebase. The repository root is not a Swift package but an Xcode project, azooKey.xcodeproj, with the app split into several first-party targets. There is AzooKeyCore, a Keyboard directory, MainApp, Resources, and two test targets, azooKeyTests and MainAppUITests. The language is Swift, the licence is MIT, and the project is not archived.

For a reader deciding whether to study or reuse it, the honest summary is that this is a complete, shipping application, not a library. You adopt it by reading it, by running it, or by forking it.

Zenzai and the converter that lives in another repository

The conversion engine is called Zenzai, and the README describes it as a neural kana-kanji conversion system included in the project. It is the reason the repository is interesting to people who work on Japanese language input at all.

The engine is split across repositories in a way that is easy to miss. The README states that details of the conversion engine are referenced from AzooKeyKanaKanjiConverter, a separate repository under the same organisation. The standard dictionary is not stored in the app repository either: it ships inside the KanaKanjiConverterModuleWithDefaultDictionary in that converter repository. If you want to change which dictionary is used, the README tells you to change the dictionary reference on the converter side.

The repository listing shows how the neural models are carried. Alongside the source directories there are zenz-v3.2-small-gguf and zenz-v3.2-xsmall-gguf, two model files in GGUF format with different size labels, small and xsmall. Their presence in the top-level tree tells you the converter ships weights rather than downloading them, which matters for app size and for anyone planning to swap in a different model.

For a developer picking this up, the practical consequence is that azooKey is the application and the packaging, while the conversion research lives next door in AzooKeyKanaKanjiConverter. Read both.

Custom keys and custom tabs inside the keyboard extension

The README lists the customisation features as custom keys and custom tabs, alongside live conversion. These are described in the summary as unique customisation features, and the repository layout backs the claim: the Keyboard directory is a separate target, and Resources holds the assets that a keyboard extension needs to render.

An iOS keyboard extension runs under tight constraints. It is launched by the system on behalf of whatever app the user is typing into, it has no network access by default, and it gets only what the host app passes through. That is why the app and the keyboard are separate targets in this project, and why MainApp exists alongside Keyboard rather than a single target with a toggle. The main app is where configuration happens, including the instructions the app shows on first launch about how to add the keyboard.

The repository also carries a scripts directory and a .swiftlint.yml file, so the project applies SwiftLint rules and has its own tooling. There is an AGENTS.md file at the root as well, which usually means agent-facing instructions are part of the contributor workflow.

What the README does not spell out is the configuration surface itself. It does not enumerate the available custom key types, describe how custom tabs are laid out, or document which settings live in the main app against which live in the keyboard extension. The overview document referenced under docs/ is where that detail is expected to be.

Building from source with submodules and Xcode

The build instructions are short and explicit. You need an Apple Developer Account, which the README says is free, and the latest Xcode. The clone step matters more than it looks, because azooKey uses submodules and the README insists you add the recursive option.

git clone https://github.com/azooKey/azooKey --recursive

Skipping that option gets you a tree whose conversion dependencies are empty, and the failure appears later rather than at clone time. The repository does contain a .gitmodules file, which confirms the submodule setup.

After the clone, open azooKey.xcodeproj and press Run, which the README writes as Command+R. The project file is checked into the repository, so there is no package resolution step and no dependency manager involved. When the app launches, it explains how to install the keyboard, and you follow those instructions; enabling a third-party keyboard in iOS Settings is a separate manual step that the app cannot perform for you.

Testing is documented in a separate file, docs/tests.md. The two test targets in the tree, azooKeyTests for unit-level checks and MainAppUITests for interface-level checks, suggest the two are run differently, but the README delegates the specifics to that document rather than describing them.

How the app is distributed and where the macOS version went

azooKey is published on the App Store, which the README states as the distribution route for the iOS and iPadOS application. A public store listing also means there is a separate, non-open channel for updates, and the build instructions above describe a developer path rather than the path a normal user takes.

There is also a beta channel. The README points to TestFlight for the in-development beta and invites feedback through Discord or issues. It also names the Discord server as the place for development questions, feature requests and bug reports, and notes that pull requests for performance work, bug fixes and features are welcome, with feature proposals best discussed in an issue first.

The macOS side is a separate project. The README points to azooKey-Desktop for the macOS version, so the two platforms do not share a repository, and any macOS evaluation means looking at that project rather than this one.

Two smaller signals sit in the README. Funding goes through GitHub Sponsors. And the release notes section says work is currently aimed at v3.0.1, which does not line up with the published tag list, where v3.1, v3.1.1-beta.1 and v3.1.1 are the recent releases. Read the tags rather than that paragraph when pinning a version.

Where azooKey will frustrate you as a newcomer

The main obstacle is documentation language. The README is written in Japanese, and the detailed documents it references, including the overview and the testing guide, are Japanese as well. There is no English documentation in the repository listing. For a Swift developer who reads Japanese this is a minor cost, but for anyone else it means reading the source to answer basic questions about configuration and behaviour.

The second obstacle is toolchain dependence. Building requires macOS, Xcode, an Apple Developer Account and a manual keyboard-enablement step in iOS Settings. There is no Swift Package Manager entry point, no CI-produced binary, and no way to run the conversion engine as a plain library from a command line as far as the README describes. If your goal is to evaluate the kana-kanji conversion quality in isolation, this repository is the wrong entry point and AzooKeyKanaKanjiConverter is the one to look at.

The third is the boundary of the platform. azooKey targets iOS and iPadOS. It cannot be pointed at Android, at desktop Linux, or at a browser. That is not a defect, but it means the useful audience is narrow: iOS developers, Japanese language researchers, and users who want a Japanese keyboard on an iPhone without a store listing.

Comparing azooKey against the system Japanese keyboard

The alternative an adopter will actually compare against is the Japanese keyboard built into iOS, which every iPhone already has and which needs no install, no Apple Developer Account and no model files. That comparison usually turns on three things.

First, conversion quality. azooKey bundles Zenzai, a neural kana-kanji conversion system, and the README claims high accuracy for it. System input methods use their own dictionaries and heuristics, and the practical difference shows up in how often a candidate word needs a manual fix. Neither the README nor the repository listing publishes a comparison, so this is where you have to try both on your own text.

Second, customisation. Custom keys and custom tabs are the project's distinguishing features and the system keyboard does not offer them in that form. If you need a differently arranged layout or a second key row set, that is a reason to move away from the system keyboard.

Third, control over the conversion data. azooKey keeps the dictionary in a module you can point at a different dictionary, and the model weights live in the repository as named GGUF files. That matters for a team that wants to ship a specific dictionary or a smaller model than the default.

None of this makes azooKey a universal upgrade. For most users the system keyboard is the cheaper choice, and the case for azooKey is strongest for people who want to modify the input method itself.

Editorial conclusion

Adopt azooKey if you are a Swift developer who wants a working Japanese input method as a starting point, if you are researching kana-kanji conversion, or if you want to read production SwiftUI keyboard extension code that ships to the App Store. Do not expect a package-manager install or an English documentation set, because the build path documented in the README is a recursive git clone into Xcode and the written guidance is in Japanese. Before starting, confirm you have an Apple Developer Account and a current Xcode, decide whether the zenz-v3.2-small-gguf and zenz-v3.2-xsmall-gguf model files in the repository are what you want to ship, and check which upstream release you follow, since the published tags reach v3.1.1 while the README still describes work aimed at v3.0.1.

Frequently asked questions

Official sources

1. azooKey/azooKey on GitHub
2. License: MIT
3. Project website
4. README
5. Releases