DeepSix Voice Guide for Translators

Audience: Anyone translating DeepSix's source strings into a non-English locale via Weblate (translate.deepsixdive.com). Status: Living doc. The first round (v1.0 — Roy van der Valk, Dutch, 2026-05-28) is the test case. Patterns confirmed in v1 will harden into rules; ambiguous cases will get spelled out as we hit them.

This file is published as the project description on Weblate and is the first thing a new translator reads. It pairs with the glossary component (dive-glossary.tbx) which carries terminology rules.

The big picture

DeepSix is a dive memory system — a "dive log app" reframed around capturing and presenting the meaning of a dive, not just its data. The copy reflects that. We're not a chatty consumer toy ("Wow, you logged 5 dives!"); we're not a pro-tool spreadsheet ("Records: 5"); we're somewhere in between — friendly enough to feel like an app you'd send a tester home with, precise enough that a technical diver doesn't roll their eyes.

The five tenets the app is built on bleed directly into the copy:

1. Aggregation & presentation — copy should make data legible, not decorative
2. Data fidelity as user trust — never round, never silently lose, never overclaim
3. Immutability — never paraphrase past events ("Logged dive #5 on Mar 17" not "Your dive on Mar 17")
4. Offline-first — copy degrades gracefully when offline ("Will sync when online" not "Failed")
5. Accuracy over completeness — "Approximately 25 m" beats "25 m" when the underlying data is interpolated

When in doubt, ask: would a careful diver who reads instrument labels in the wild trust this copy?

Tone

Friendly-technical. Warm enough to acknowledge the user is a person, precise enough to be trusted with their dive data.

Right:

• Saved your gear list. We'll remember it for next trip.
• No dives yet — let's log your first one.
• Looks like 2 dives are missing depth data — want to estimate from your computer's profile?

Wrong:

• Gear saved!! 🎉 (too consumer-toy)
• Gear list saved. (too terse for greetings/empty states; OK for system result toasts — see Voice below)
• Your gear configuration data has been persisted to local storage. (over-precise; reads as developer noise)

The "we" voice appears in framing copy — settings save toasts, empty states, onboarding moments where tone matters. Direct address ("you", "we'll") is allowed there. It does NOT appear in action confirmations or result toasts (see Voice).

Voice

Imperative for actions. System-as-actor for results. Don't address the user as the subject of an action.

Don't write You deleted this dive. or We removed 3 photos. in result toasts — the result toast describes what happened to the data, not who did it. The framing tone is "we" / "you"; the action results are "Saved" / "Deleted" / "Removed N items."

Terminology

Dive computer + decompression terms appear with the native term first, English in parentheses on first occurrence on each screen. Subsequent mentions on the same screen use just the native term.

Rule of thumb: if the term appears on the user's dive computer in English (Shearwater, Garmin, Suunto, all English by default in most regions), the English form needs to be visible in the app too — even when wrapped in a native explanation. A diver should be able to map the app's display back to what their computer shows them.

The full never-translate + translate-carefully list lives in dive-glossary.tbx and is loaded into Weblate's glossary component. Translators see inline glossary hints when a glossary term appears in a string they're translating.

Uncertainty

When a value is approximate, estimated, or unknown, use symbol prefixes for compactness:

Localize the prefix character to whatever your locale convention is — e.g., a locale where ~ reads ambiguously can swap to a different glyph. But preserve the visual hierarchy: prefix → value → unit. Don't suffix the qualifier (avoid 25 m (est.)); the symbol prefix reads scannable in tight stats grids.

Accessibility labels (VoiceOver / TalkBack) should spell out the qualifier even though the visual is symbolic: Approximately 25 meters, Estimated 18 minutes, Unknown water temperature. xcstrings handles this via separate accessibilityLabel keys where it matters.

Plurals

DeepSix uses xcstrings native variations.plural for all count-bearing strings. Do not write English-style suffix mechanisms (dive%@ for dive / dives) — those are bugs being progressively removed from the source catalog.

Your locale will see CLDR plural categories. Fill the ones your locale needs:

• Dutch, German, Spanish, French, English, Italian, Portuguese — one (n=1) + other (everything else)
• Polish — one + few + many
• Russian — one + few + many
• Arabic — zero + one + two + few + many + other
• Japanese, Chinese, Korean, Vietnamese, Thai — other only (no grammatical plural)

If a category isn't in your locale's CLDR rule, Weblate hides it. You only fill what's relevant.

Numbers, units, and formatting

DeepSix already converts SI ↔ imperial at the display layer via UnitPreferences — translators don't pick units. Do translate:

• Number formatting (thousands separator, decimal point) — these follow the user's locale automatically via NumberFormatter, you don't need to do anything
• Unit labels (m, ft, °C, °F, bar, psi, kg, lb) — keep these in their canonical SI form unless your locale has a strong convention otherwise (e.g., Spanish dive community uses "m" not "metros" for depth)
• Time formatting (durations like 18 min, 1 h 23 min) — translate the unit shortcuts to your locale's conventional abbreviation

Don't translate:

• Numbers themselves
• Format-specifier characters in source strings (%lld, %@, %.1f)
• File format names (UDDF, FIT, CSV, XML, JSON)
• Vendor names (Shearwater, Suunto, Garmin, MacDive, Subsurface)

Honesty patterns

Per the accuracy tenet, copy never overclaims. Translate these patterns carefully — the exact language matters:

If a source string seems to overclaim in English, flag it via Weblate comment — it's probably a source bug.

When to ask vs guess

Use Weblate's source-string comment ("Add comment") to flag:

• A source string that's structurally broken (e.g., another word%@-as-plural-suffix string we missed; an unclear placeholder; gender assumptions in English that don't map to your locale's grammar)
• A glossary entry that's wrong for your locale
• Multiple plausible translations where context isn't clear

Don't guess silently. The source-string author (often Rick + Claude in this codebase) sees the comments and either fixes the source or replies with context.

What's NOT translated (excluded entirely)

These keys are marked shouldTranslate: false in Localizable.xcstrings and don't appear in Weblate at all:

• Debug log strings (developer-mode only)
• Format identifiers (UDDF, FIT, ZHL-16C, etc. — these are protocol/spec names)
• One-off developer-mode UI strings

If a string you'd expect to see is missing from Weblate, it's been deliberately excluded. If it should be visible, surface to Rick — it may be a tagging mistake.

Cross-references

• dive-glossary.tbx — terminology dictionary (loaded into Weblate's Glossary component)
• Scripts/sync_translations.py — the deeplog ↔ deepsix-translations broker
• Scripts/verify_translations.py — automated checks (placeholder integrity, glossary compliance, optional AI consistency review)
• deepsix-translation-tiers-spec.md — Core / Full / Excluded tiering for release inclusion
• DeepSix product tenets (5 in total) — referenced at the top of this doc; see user_product_vision.md if you have access

This guide is living. If a pattern surfaces that this doc doesn't cover, surface it via Weblate comment and we'll add it. v1.0, 2026-05-29.