Offline travel tools: why a cached homepage is not enough

A travel tool should not say it is ready offline just because its homepage opens without a connection. The useful question is whether the traveler can still reach the needed content, read it, and recover from an interrupted update. Those are separate tests.

Disclosure: this is a developer's implementation note about China Phrases, a mobile web tool for prepared Chinese travel communication. It was drafted with AI assistance and checked against the project's implementation and automated tests on 30 October 2026. It is not an independent review, a traveler interview study, or a claim about adoption.

The product boundary comes first

The tool contains prepared text for specific situations, such as a passport booking or a metro gate problem. Its offline fallback is readable text. It does not need a live translation model to generate each phrase. That keeps one dependency out of the moment when a traveler needs help, but it does not make every feature available offline.

Speech is a separate capability: the app uses the device's speech facilities rather than a bundled audio library. A working text download is therefore not evidence that speech will work on the same phone without a network. Purchase checks and account actions also need their own online states. A single green badge should not blur these boundaries.

Cache a complete release, not whichever files happened to load

In this implementation, a release manifest identifies each required file by path, byte length and SHA-256 digest. The service worker fetches those files into a release-specific cache. It checks each response before storing it and checks completeness before reporting readiness.

Why include both size and digest? A request can return a successful HTTP response while delivering an unexpected body. A release check asks whether the bytes match the expected package, rather than treating status 200 as proof of usable content. This is a consistency check, not a substitute for HTTPS or a signed distribution system.

If installation fails, the incomplete new cache is removed. The previous release is preserved. That matters more than displaying an optimistic download animation: an interrupted refresh should not erase the working copy someone already prepared for a trip.

Updating and using are different moments

A downloaded update should not automatically replace an active phrase screen. In the current worker, activation is requested with an explicit update message. The worker rechecks the candidate package before accepting that request. A missing or corrupt file keeps the update from becoming active.

This gives the interface a concrete contract: “downloaded,” “ready to apply,” and “currently in use” can represent different states. The interface must report the worker's result rather than infer success from a button click. Otherwise, it can promise an update that the underlying cache rejected.

Do not reuse cached payment responses as fresh truth

The worker deliberately leaves API, checkout and license requests outside its static-resource cache handler. Static text and a transaction's latest status have different freshness requirements. An offline shell can remain useful without pretending that a new payment has been confirmed or that account recovery has just succeeded.

For another small app, the exact route names may differ. The important design decision is to draw the cache boundary explicitly and review it when new features are added. “Cache every GET” is too broad a product rule.

What the checks actually established

Eight focused worker tests passed on 30 October 2026. They cover a corrupt package during installation, readiness after cache corruption, explicit activation of a verified update, refusal of missing and corrupt updates, an activation error, and two navigation cases involving redirected app-shell responses.

These are controlled tests using a simulated worker environment. They establish behavior for those inputs; they do not establish reliability across every mobile browser, storage pressure, operating-system update or real journey. No user-retention or conversion improvement is claimed.

A separate device acceptance check should download the release, disconnect the network, reopen the app, navigate to a previously unopened situation, display its Chinese text, and attempt an update interrupted halfway through. Speech needs its own test. Browser storage can be removed or evicted, so a fresh readiness check is more useful than a permanent “offline” promise.

A reusable acceptance question

Before shipping an offline badge, ask: which exact action remains possible, which saved content does it depend on, and what evidence confirms that content is present? A cached homepage answers only a small part of that question.

Technical background: MDN's guide to offline and background operation explains the service-worker and cache model. The implementation discussed here belongs to China Phrases; this article describes its development decisions, not a general guarantee for PWAs.