When the network can interrupt learning
Nihongo Pocket is a Japanese learning app for people whose first language is Burmese. It brings vocabulary, conversations, drills, reading, and a dictionary together from N5 to N1, with Japanese audio and Burmese explanations.
The design did not begin with a long feature list. It began with the conditions in which the app would be used.
Network speed in Myanmar can vary by region and time of day. Power outages and dropped connections can interrupt a download, and asking someone to keep a large transfer alive is not a practical default.
The core requirement was therefore simple: connectivity can make the app more convenient, but losing connectivity must not stop learning.
The technology stack
The mobile app is built with Expo, React Native, and TypeScript. Expo Router handles navigation, while progress and download state are stored in SQLite on the device.
The main stack includes:
- Expo 57 / React Native 0.86 / TypeScript
- Expo Router
- expo-sqlite for progress and downloaded content
- expo-file-system for persistent content and audio storage
- expo-audio for playback of downloaded Japanese audio
- expo-background-task for resuming interrupted download work
- Cloudflare Workers and Hono for manifests and progress APIs
- Cloudflare D1 for anonymous-user progress backup
- Cloudflare R2 and CDN delivery for audio, content JSON, and images
- a Node.js and TypeScript content CLI for validation, TTS, pack builds, and publishing
Learning results are written locally first. Server synchronization is a recovery feature, not a gate that must respond before the learner can continue.
A small starter that works on first launch
The app bundles a small starter with the first vocabulary stages, one story, and the audio they need. Learning can begin immediately even if the first launch happens without an internet connection.
The rest of the curriculum is divided into level- and theme-based packs. A pack is typically 3–6MB, so learners can download only the level or topic they need.
Downloaded packs remain on the device and work fully offline, including audio. Packs can be removed to free storage without deleting learning progress.
Choosing not to stream audio
Pronunciation audio is essential in a language-learning app. Fetching it every time it is played, however, creates delays or silence when a connection is slow.
Nihongo Pocket pre-generates Japanese speech with Irodori TTS, distributes it through R2, and plays it from the device after download. Missing audio is not streamed on demand. The app only plays a file once it can do so reliably.
Audio is encoded as 32kbps mono MP3 at 24kHz. This keeps transfers small while preserving clear speech for study. A shared loudness-normalization step keeps vocabulary, examples, and story dialogue at a consistent level.
From 9,657 HTTP requests to 101
Downloading thousands of small audio files creates thousands of HTTP connections. On a high-latency network, the connection overhead can matter as much as the file size.
The delivery pipeline therefore creates an audio.bundle, which concatenates already-compressed MP3 files without recompressing them, and an audio-index.json that records each file's offset, byte length, and SHA-256 hash.
Across 37 packs and 9,620 audio clips, this reduced the initial request count from 9,657 to 101, a 98.95% reduction. The largest bundle is about 4.24MiB.
After download, the bundle is split into individual audio files on the device and every file is verified. On an update, unchanged audio is reused from the previous version and only changed files are fetched again.
Resume after a power or connection interruption
Completed files are kept when a connection drops. State and byte progress are stored in SQLite, and the queue resumes after launch, foreground return, or network reconnection.
Learners can pause and resume downloads. A Wi-Fi-only preference keeps queued work waiting while the device is on cellular data.
The small content JSON is fetched before the audio, so text study can begin even while speech files are still downloading. The interface does not block behind an endless loading state.
Files are verified with SHA-256. A mismatched file is discarded and downloaded again. Versioned, immutable URLs allow the verified previous pack to keep working until the replacement is complete.
AI output, followed by native-speaker judgment
Writing thousands of vocabulary entries, examples, conversations, and drills entirely by hand from the first draft is not realistic. AI helps produce candidates, find duplicates, validate character sets, and challenge whether a quiz really has only one correct answer.
But Burmese that an AI considers natural may still feel wrong in an everyday conversation.
My wife is from Myanmar and is a native Burmese speaker. Rather than treating AI output as final, I review the meaning and then ask her to check how translations and interface phrases actually sound to a native speaker. Her feedback can then go back into the content and interface.
The process is AI drafting and first-pass review, deterministic validation, developer judgment, and native-speaker feedback. Because the curriculum is large, an AI review is never recorded as native approval. Review states remain explicit while native feedback is expanded from important interface and learning language.
AI is useful for scale and finding patterns. A native speaker is better at context, social distance, and the phrasing people really use. Giving each a different role has produced better results than asking either one to carry the whole process.
Start with the user's environment, not the easiest implementation
Streaming every audio clip would be simpler if fast connectivity could be assumed. The real environment changed the priorities: preserve completed work, avoid waiting, resume after interruption, and reuse every byte already on the device.
Offline support in Nihongo Pocket is not an extra feature. It is the requirement that shapes the data model, audio format, delivery unit, interface, and tests.