hyperlocalise smartling to upload source files, inspect translation status,
and download published translations. Smartling file and resource operations share
one executable with local AI translation and other TMS commands in the
all-in-one localization CLI.
Start with a Smartling upload and download
Install Hyperlocalise. SetSMARTLING_USER_IDENTIFIER and SMARTLING_USER_SECRET in your shell or CI secret
manager for a credential with project access. Prepare locales/en.json, then
replace the project ID and use a target locale enabled in Smartling:
--authorize=false leaves authorization to your Smartling workflow;
Hyperlocalise otherwise defaults to authorizing uploaded sources. Review the
export before committing. See download published Smartling translations
for status checks and multi-file downloads.
Hyperlocalise vs the official Smartling CLI
Hyperlocalise is a Smartling CLI alternative for the documented file workflows. Command names, credential variables, and upload defaults differ from the official Smartling CLI.
Prefix commands in the last column with
hyperlocalise. Check retrieval type,
output paths, and authorization explicitly before replacing an existing script.
Command reference
tm also accepts the alias translation-memory.
These commands are flag-only. Hyperlocalise does not read smartling.yml in this version.
What this command family does
These commands talk to the Smartling Files, Projects, Accounts, Glossary, and Translation Memory APIs. They are separate from Hyperlocalise nativei18n.yml and sync push / sync pull workflows. Use shared TMS sync when you want Hyperlocalise-managed entry sync through the Smartling adapter. Use this surface when you want flag-driven file upload and download against a Smartling project.
Use them for:
- discovering locale IDs (
locales list), file URIs (files list), and project IDs (projects list/projects info) - checking one file’s translation progress (
files status) - renaming or deleting one exact file URI (
files rename,files delete) - source-file upload (
upload sources) - import of a pre-translated locale file (
upload translations, equivalent to officialsmartling-cli files import) - source download (
download sources) - translation download (
download translations) - glossary and translation-memory download (Hyperlocalise-shaped CSV/TMX)
files push / files pull (aliases upload / download) and files import. Hyperlocalise keeps the same command family shape as Crowdin and Phrase (upload sources, download translations) instead of renaming to files push.
Credentials
Hyperlocalise reads:--user-id, orSMARTLING_USER_IDENTIFIER--user-secret, or--user-secret-env(defaultSMARTLING_USER_SECRET)
smartling-cli commonly uses SMARTLING_USER_ID and SMARTLING_SECRET. Those names are not read here. Export Hyperlocalise names, or pass --user-id and --user-secret / --user-secret-env.
Do not put the user secret in i18n.yml. Do not commit smartling.yml that contains a secret.
File types
When--file-type is omitted, Hyperlocalise infers Smartling fileType from the path extension:
Unknown extensions require
--file-type. Values such as android or gettext are valid when you pass them explicitly; they are not inferred from .xml or .po.
Command notes
locales list prints source and target locales as locale=... source=true/false lines (enabled=true/false when Smartling sends it). Disabled locales stay in the list so you can see why a download failed.
files list prints every file URI in the project. --uri-mask is Smartling’s substring filter, not a glob: en.json matches locales/en.json. Do not pass --file-uri here; that flag means an exact URI on upload, download, status, rename, and delete. Empty projects print nothing in text mode (no output means no files) and [] with --output json. Both exit 0. --output is text or json.
files status requires --file-uri for one file. It does not check whether a matching file exists on disk. Text progress uses each locale’s authorizedStringCount / authorizedWordCount as total_strings / total_words. File-level totalStringCount from Smartling is often 0, so the file header omits those totals. percent is completed strings over authorized strings (0 when nothing is authorized).
files rename and files delete take one exact --file-uri. There is no mask or glob. --dry-run prints the planned request and does not call the network. Delete is asynchronous: success means Smartling accepted the request. Re-uploading the same URI may fail until that delete finishes. Hyperlocalise does not poll.
projects list requires --account-uid. Use the same account id as glossary download --account-uid.
projects info requires --project-id. Text output is project_id, name, account_uid, source_locale, and archived=true|false. Target locales stay on locales list.
upload sources requires --project-id and at least one --file. --file-uri is optional for a single file (defaults to the path with / separators) and cannot be used with multiple --file values. --authorize defaults to true (official files push leaves jobs unauthorized unless --authorize is set, and often wraps uploads in a translation job). Repeat --directive key=value to send parser hints; Hyperlocalise prefixes the form field with smartling. unless the key already has that prefix. The same directive with and without the prefix is a duplicate and is rejected. foo with no = is an error before any network call. --dry-run prints the planned upload (including directives) and does not call the network.
upload translations imports translations for an existing source file URI. Pass exactly one of --published or --post-translation. The source file must already exist in the project. JSON/XML imports may require Smartling source_key_paths on the original source upload (upload sources --directive source_key_paths=...). One --target-locale per invocation.
download sources writes to stdout when --output is omitted or -. --source-locale is deprecated and ignored. --force overwrites an existing output file. --dry-run does not download.
Pass exactly one of --file-uri or --all. --all lists files (same paging as files list, optional --uri-mask) then downloads each URI. --uri-mask is only valid with --all. --output is then a directory (default .). Local names match official smartling-cli default pull format: URI locales/en.json writes locales/en.json for sources and locales/en_fr-FR.json for --target-locale fr-FR. Do not pass - or %locale% with --all. An empty list is a non-zero error. --all --dry-run lists files (credentials required) and prints planned paths without downloading bytes. Downloads run sequentially and stop on the first error.
download translations omits --target-locale to download every locale listed in file status for each URI. When you pass --target-locale, Hyperlocalise intersects your values with file status (case-insensitive) and uses Smartling’s locale IDs from status. --all resolves locales per file URI, not once for the whole project. --dry-run still calls file status (credentials required). Use %locale% in --output when you download more than one locale for a single --file-uri. --retrieval-type is pending, published, or pseudo. If you omit it, Hyperlocalise does not send retrievalType and Smartling uses its default. Prefer --retrieval-type published when you only want published text.
glossary list searches glossaries on an account (--name is an optional search query). glossary create needs --name and at least one --locale. glossary import uploads Smartling’s official glossary import CSV (not the Hyperlocalise-shaped CSV from glossary download), confirms the import, and polls until Smartling finishes.
glossary download and tm download have no --force or --dry-run. They write CSV (or TMX for tm --format tmx) to stdout unless you pass --output.
smartling-cli gap inventory
Examples
List locales, then files, then status for one URI:source_key_paths on this source upload:
%locale% when you pass more than one --target-locale:
--target-locale to pull every locale from each file’s status: