Returned translations need the exact original catalog
Understand source hashes, protected rows and byte preservation before collaborative translation handoff.
A collaboration request has a specific handoff
The source author wants friends to help edit XCstrings, with online access preferred for collaborators on Windows. The public question did not include the real catalog, so a browser tool must declare its supported shape rather than assume every catalog has direct units.
Whitespace belongs to the identity of the original
A returned translation table is bound to the raw source hash. A formatting-only change may preserve parsed values but still changes that hash. Export again when the source changes; matching a key name alone does not establish which revision a translator edited.
"opaqueRevision": 9007199254740993,
"opaqueFraction": 0.125Existing direct units and variants have different review needs
A direct value/state exchange is straightforward to bind. Plural, device and substitution branches need catalog-aware semantics; flattening them into a single translation can discard required branches. Keep the complete original and rejected diagnosis for an appropriate editor.
| Field | Handling |
|---|---|
| value / state | Edit an existing direct unit |
| valuePath / sourceLocale | Preserve every row and its order |
| sourceSha256 / version / sourceLanguage / columns | Preserve exact binding and headers |
A full report is different from its preview
A short screen preview keeps large deliveries usable. It must not replace the complete original, updated catalog, table or refusal diagnosis. Read the full change list and let the receiving Xcode project validate the imported catalog and its locale requirements.
- Keep the exact original catalog used to export the translation table.
- Ask collaborators to edit only existing value/state cells and retain protected fields, row order and headers.
- Apply the return to that original, review the complete change report, then verify the updated catalog in the receiving Xcode project.
- If the catalog contains refused variants, retain the original and full diagnosis for a catalog-aware editor.
References
- Collaborative XCstrings editor request
The author wants friends to help edit and prefers online access because some use Windows. No actual author catalog was provided; this supports the task, not every schema or demand volume.
- Apple string catalog documentation
String catalogs can contain variations. This tool deliberately refuses those shapes and exchanges only existing direct units.
Tools in this category
Expand a tool to see its steps, options and supported formats, then open its workspace.
XCstrings manual translation exchangeExport existing direct translations and states for collaborators, then apply a complete returned table or a SHA-bound partial patch while retaining untouched catalog bytes.
Export existing direct translations and states for collaborators, then apply a complete returned table or a SHA-bound partial patch while retaining untouched catalog bytes.
Steps
- Choose Export table and select the original catalog.
- Send manual-exchange.json to collaborators. Edit only value and state in a JSON editor, keeping the protected fields and every row.
- Choose Apply complete table, select the same byte-exact original and the entire returned JSON; or choose Apply partial patch and supply explicit before values.
- Review counts and the full change report, download the updated catalog, then validate it in the receiving Xcode project.
Available options
- Task
- Export complete exchange table · Apply complete returned table · Apply explicit partial patch
Capabilities and limits
- Select one strict UTF-8 XCstrings 1.0 or 1.3 original, at most 5 MiB, without BOM. Import also requires one returned JSON File: a full table up to 16 MiB or an explicit partial patch up to 5 MiB. Two file roles and all options, sizes and scalar Unicode names up to 512 UTF-8 bytes are checked before any complete read.
- Export every existing direct stringUnit value and state. Supported states are new, needs_review and translated. Locale names are opaque fixed keys; this does not certify their validity in Xcode. Empty entries/localizations may be retained, but new locales or units are not created.
- In the complete returned table, edit only value and state. Preserve format, sourceSha256, version, sourceLanguage, columns, every row, row order, valuePath and sourceLocale. A partial patch uses explicit valuePath, originalValue, originalState, value and state for each edit; unknown or repeated paths and before-value conflicts reject the whole import.
- Any variations or substitutions at root, entry, localization or unit scope, unknown state, or unknown localization shape refuse the whole operation. The failed screen retains byte-exact original.xcstrings and the complete unsupported-shapes.json with whole-file copy/download. A fatal structural prerequisite has a separate non-exhaustive diagnosis; it is never presented as a successful updated catalog.
- At most 10,000 entries, 50,000 localization records, 50,000 direct units, 64 JSON container levels and 1,000,000 JSON tree nodes. The mature scanner counts containers/literals plus property nodes before recursive parsing; key strings count too. Duplicate keys, malformed JSON, invalid UTF-8 or escaped lone surrogates fail atomically.
- Each complete exchange or updated catalog is at most 16 MiB. The complete import change report has a derived 40 MiB capacity; all artifact bytes together are capped at 61 MiB. Failed artifacts stay within 5 MiB original plus 16 MiB diagnosis. No output is silently shortened to fit.
- Outside selected value/state string tokens, the original UTF-8 bytes remain exact: comments stored as metadata, spacing, CRLF, unknown objects, fractional numbers and unsafe-integer numeric lexemes are retained. The original download is never a JSON reserialization.
- A host deadline of 10 seconds includes File reads, Worker loading, readiness, calculation and complete result validation. Cancel settles immediately and terminates any live Worker; late reads/replies are ignored. Rerun the same original Files and options after stopping. Previews show at most 4,000 Unicode code points; copy/download retain every byte of each complete artifact.