How do you manage Weblate translations from a terminal without accidentally overwriting reviewed work? The Weblate Client, normally invoked as wlc, uses the Weblate REST API to inspect projects and components, download translations, upload files, and coordinate repository synchronization. This tutorial explains the wlc CLI workflow, configuration security, translation states, import methods, Git integration and localization quality assurance.
Weblate is often connected to a source-code repository, which makes its lifecycle different from a simple folder of translated documents. Developers change source files, translators review units, Weblate tracks translation state, and the repository receives or supplies revisions. A successful terminal command does not prove that all these parties agree on which version is authoritative.
This world-facing guide is for open-source maintainers, localization coordinators, engineers and translators who need reproducible multilingual releases. It explains how to use the current Weblate Client documentation, including API endpoint configuration, project and component discovery, remote repository operations, upload conflict behavior, review status and end-to-end rendering. Begin with read-only exploration before any write.
- Discover the correct Weblate project, component, API endpoint and repository branch.
- Keep credentials and project configuration within trusted boundaries.
- Separate read operations, uploads, approvals and Git synchronization.
- Check conflict policies, translation states, fuzzy entries and source changes.
- Validate downloaded resources, Unicode and the actual user interface.
1. Understand the boundary between Weblate and wlc
Weblate is the collaborative translation service; wlc is the separate command-line client that talks to its REST API. The tool does not perform the human translation work or replace project configuration. It provides access to server-side actions. That separation matters because permission, workflow states and repository behavior are controlled by the Weblate instance, not simply by the command on a laptop.
Before using the CLI, identify the instance, organization, project, component, branch and file format involved. Ask which repository the component synchronizes with and how the source language is determined. An incorrect component selection can produce technically valid operations against the wrong material, making a good translation appear missing or overwritten.
Start by listing projects and components with read-only commands, then inspect one component you know. Compare its source files and target locales with the repository. Do not use upload as a discovery method. Read-only inspection builds a map of what the server owns and makes later commands easier to review.
2. Install a client that matches current documentation
The official Weblate Client can be installed through Python packaging and may be invoked with wlc. The documentation also describes alternatives such as uvx and container images. Choose a controlled installation mechanism for the environment rather than mixing several binaries named alike. Tool version matters because flags and security defaults can change.
Use the command’s help and version output in a test workspace. Check whether the deployed Weblate server is compatible with the features your automation intends to call. Do not assume that documentation for a newer server describes every capability of an older hosted instance. The command exists at the boundary between two separately versioned systems.
Pin a tested client in continuous integration and record the server URL. A build should be reproducible from the same source revision and client version. When upgrading, first repeat read-only commands and compare output, then test a safe upload on a noncritical component. Never use production reviewed strings as migration test material.
3. Scope the API endpoint before providing credentials
wlc connects to a Weblate API endpoint, not merely to a public project homepage. On a hosted instance, the API path is distinct from human-facing translation pages. A mistaken endpoint can cause confusing authentication errors or direct content to an unintended service. Confirm the host and scheme with the instance administrator.
Current Weblate Client documentation emphasizes configuration trust. A repository-local configuration can select the destination API server and matching credential. Running a command inside an unfamiliar checkout therefore deserves the same caution as running its build scripts. Do not blindly load project configuration from an untrusted pull request while injecting powerful secrets.
Use an explicit trusted configuration file where appropriate, inspect its selected endpoint and restrict credentials to the intended host. Treat output downloaded from the server as data that must be validated. The client cannot establish that a malicious or misconfigured project is trustworthy simply because the API responds successfully.
4. Treat API keys as scoped authority
The client can receive an API key through supported options, environment variables such as WLC_KEY, or configuration. These choices serve different deployment needs. A developer’s interactive token may be convenient, but an unattended job should use a managed secret with appropriate permissions and a clear rotation owner.
Access should match the job. A read-only translation export does not require the authority to edit units, push repository changes or alter approvals. Review whether permissions are actually constrained by the server. A shell command executed with an administrator’s token can have consequences far beyond the local files visible in its working directory.
Inspect logs for accidental disclosure, and avoid placing secrets in command-line history or shared troubleshooting transcripts. The official documentation notes specific security behavior for debug output, but users should still inspect the context in which they execute the tool. Validate secret rotation with a harmless read before attempting the first write.
5. Understand project, component and translation objects
A Weblate project can contain several components, and a component can contain multiple language translations. This hierarchy explains why a project-level status is not enough to identify the resource that needs attention. Components may represent an application’s frontend, server messages, documentation or a separate release stream.
A team may maintain one product but several repositories or file formats. If all changes are downloaded at project level without verifying component boundaries, an import could touch more files than the application release needs. The right unit of work is often the specific component that owns the strings being changed.
Use project and component listings to map the resource tree. Compare the component’s file names, source language and Git settings with repository expectations. Record that mapping in human-readable documentation so collaborators can distinguish, for example, the web checkout messages from the backend notification templates.
6. Check the repository integration before syncing
Weblate can integrate translation updates with version control. Commands such as commit, push and pull therefore have meaning beyond downloading a file to a workstation. A server-side commit may gather translated changes, a push may send them outward, and a pull may bring upstream repository changes into Weblate, subject to the component’s configuration.
Suppose the upstream repository changes string identifiers while translators are reviewing old text. Synchronizing too early may create fuzzy entries, conflicts or obsolete units. Synchronizing too late may cause reviewers to work against an outdated source. Plan a cadence that matches release branches and reviewer availability.
Before invoking a repository operation, inspect the component’s state, branch and upstream relationship. Keep a rollback plan that distinguishes the Weblate server’s repository state from your local checkout. Review changes in Git after synchronization and verify that intended source and translated resources were updated together.
7. Distinguish read-only reports from state-changing commands
A listing or statistics command helps you understand the current project. An upload, edit-unit, approval or repository operation may change translation state or files. Treat these categories differently in scripts. A read-only discovery stage can run on a pull request, while a write stage should be gated by repository trust, reviewer approval and restricted credentials.
For example, a CI job that merely checks translation coverage should not upload incomplete resources back to the server. It can report which languages are lagging and leave editors to manage quality. Conversely, a deliberate approved upload should record why it occurred and which units were affected.
Make the distinction visible in job names and runbooks. Use predictable exit handling, and do not retry a potentially state-changing request indefinitely without checking whether the first request partially succeeded. Idempotency must be established for the specific operation rather than assumed from the existence of an API.
8. Download a translation without confusing it with approval
wlc provides download functionality for translation material. The client can transfer a file that still needs editorial review or application tests. A successful download tells you that a server produced content; it does not certify the grammatical quality or consistency of that content with the release source.
Download to an isolated path. Compare the file’s schema, encoding and source alignment against the current application. For gettext or other structured formats, run the appropriate parser or format validator. Where a locale can contain fuzzy or incomplete units, decide how the build should treat them rather than silently accepting everything.
Inspect a few important messages at the rendered interface level, including error states, plurals and links. Record the component, locale and source revision used. If the exported file changes unexpectedly, investigate server-side state and repository sync before assuming someone edited a translation.
9. Understand upload methods before importing
Weblate’s upload operation supports methods with different treatment of incoming content, including translation-oriented and approval-oriented choices. The exact methods and flags depend on the current client and server. An imported translation may be a proposal, translated content, or content that enters a more authoritative review state.
A volunteer submits corrections to a language file that also contains already approved strings. Uploading the whole file with an inappropriate method could affect review states or replace content that a maintainer had verified. The right choice depends on whether the incoming material is trusted, how conflicts should be resolved, and what history must be preserved.
Use a small controlled test with one empty unit, one translated unit, one approved unit and one ambiguous edit. Inspect how the method affects their states and attribution. Write down the expected behavior before applying it to an entire locale. Do not use a powerful import method simply to avoid manual review.
10. Treat conflict policy as an editorial decision
The Weblate Client’s upload reference describes conflict choices such as ignoring conflicting translated units or replacing particular classes of translated and approved material. Those are not just technical switches. They express a policy about whose text wins when an incoming file differs from the server.
Consider a reviewed warning already approved in Weblate. An older offline file contains a shorter and less precise version. If the upload replaces approved content, quality can move backward while the command still succeeds. In another case, refusing all replacements may prevent a legitimate emergency correction from arriving.
Test conflict settings against representative units and retain a before-and-after record. Require a named reviewer for changes that can replace approved translations. If the tool offers a default, verify that default rather than inferring it. Conflict resolution should preserve both accountability and the ability to correct mistakes quickly.
11. Know the difference between translated and approved
Translation status is a workflow property, not a universal measure of linguistic correctness. A translated unit may be awaiting a reviewer; an approved unit may still need to be tested in context after a product redesign. Teams should define what each state means for their release rather than assuming labels alone make language ready.
An interface could have complete text coverage but contain an ambiguous purchase button. Its approved status does not repair the problem if the underlying product action was misunderstood. Reviewers need screenshots, source behavior and the market context to verify meaning. The final gate should include actual user journeys.
Create a clear approval policy: who can approve, which strings need extra scrutiny, what happens when the source changes, and how urgent corrections are handled. Use status reporting to guide work, but supplement it with semantic review and automated technical checks.
12. Preserve fuzzy translations as review signals
When source text changes or similarity matching suggests an old translation, a unit may need further attention. Fuzzy status should signal uncertainty rather than be concealed as a finished answer. Some build workflows exclude fuzzy strings; others may expose source-language fallback. Review the format and application behavior explicitly.
Suppose the source changes from Save changes to Save and publish. Reusing the old translation without review can remove a consequential action from the user’s understanding. The shorter original may look close to the new one in a text-similarity system, but the user’s commitment has changed.
Inspect changed-source units by consequence and context. If an import method processes fuzzy content, verify whether it leaves review pending or changes approval. Do not force a translated state purely to raise a percentage. A visible work queue is preferable to hidden inaccuracies.
13. Keep plurals, placeholders and markup intact
Localization files often contain variables, select expressions, formatting codes or plural categories. A translated sentence may need a different word order, but variable names and parser syntax are part of the application contract. Reviewers must know which elements are translatable and which cannot change.
A notification might combine a person’s name with an item count. English plural handling may be insufficient for the target locale, while a missing variable could make the message render literally or crash. String-level tests should exercise representative values, including zero and larger quantities, rather than only checking one default example.
Compare token identities and parse each resource with the actual runtime format. Then have a competent reviewer check sentence structure. Automated validation can catch broken syntax, but it cannot guarantee that word order, politeness or legal meaning is correct.
14. Check Unicode from server to application
Weblate may store text correctly while another layer alters encoding or display. Test the complete path: editor, API, downloaded file, repository, build and runtime. UTF-8, normalization and escaping matter, but so do font coverage, text direction and accessibility technologies.
Use representative accented text, combining marks, East Asian scripts, right-to-left sentences with numerals, and emoji where relevant. Do not normalize protected identifiers or API keys merely to improve appearance. A file can look right in an editor but contain different code points than an exact-match system expects.
Verify rendering and interaction on actual devices or browsers. Copy and paste mixed-script identifiers, inspect cursor behavior, test screen-reader labels and check text expansion. Report language mistakes separately from layout and encoding bugs so each problem reaches the right expert.
15. Protect translation context and source intent
A short source string is often ambiguous. A word such as Draft could mean an unpublished article or an action involving a financial instrument. The translator needs to know the screen, the previous user action, the following action and any regional terminology constraints.
Provide component descriptions, screenshots and notes about variables. When source code uses the same English string for several meanings, consider separate keys. Context is especially important for permission changes, billing steps, medical warnings and account-security actions.
Feedback from translators can reveal that the source is underspecified. Fix the source when necessary and let related translations be reconsidered. Maintaining context prevents repeated errors more effectively than repeatedly importing a vaguely translated file.
16. Design a reviewable release boundary
Separate routine synchronization from the decision to ship. A useful release sequence records the source revision, server component, approved locale set, export settings, validation results and application tests. All six must correspond to the same product version.
An urgent source change can make previously approved translations stale. Before downloading, ask whether the critical messages have been re-reviewed and whether the server has synchronized the intended upstream branch. A mismatch here can produce accurate translations for the wrong application revision.
Freeze or pin the translation artifact used for the release, keep a rollback copy, and test with realistic user data. This lets support reconstruct what customers saw rather than relying on whichever translations are currently displayed in Weblate.
17. Use download scope deliberately
An export can cover one translation, a component or a broader grouping depending on supported command and configuration. Bigger scope is convenient only when every included artifact belongs to the intended release. Name the target locales and component explicitly when practical, and inspect the output tree before committing it to version control.
A documentation project may contain maintained manuals and an experimental tutorial. A broad download can collect unreviewed tutorial translations along with approved manuals. Both files may be valid, but only one is ready for distribution. Scope the export to the release’s content owners rather than the full project by habit.
On every download, verify expected filenames, file counts, locale codes and schema. Where a file is absent, investigate project configuration and progress instead of inventing an empty replacement. An export procedure should distinguish missing output, intentionally disabled locale and legitimate empty content.
18. Understand server-side repository commands
The wlc command set includes operations for committing translation changes and coordinating pull or push with the component’s repository. Their behavior depends on the server configuration. Before invoking them, know whether Weblate uses a branch or dedicated translation repository, and which upstream permissions are available.
A team with protected default branches may expect translation changes through pull requests rather than direct updates. If a command is used without understanding that policy, synchronization may fail or create changes that bypass the intended review. The solution is not to weaken repository protection automatically.
Test repository operations in a controlled component. Examine the resulting commits and compare them with the expected translation files. A successful server command must still be reconciled with source review, CI status and application versioning. Never interpret push success as approval of linguistic meaning.
19. Compare upload conflict strategies on real examples
Conflict handling should be validated using representative unit states. The client reference documents choices that ignore or replace translated content, including approved content. The exact outcome depends on the method and server state, so build a small test where differences are intentional and easy to inspect.
For example, place an approved warning in Weblate, a changed version in an incoming file, and a separate untranslated label. Try the contemplated policy in a sandbox and record what changes in each unit. This reveals whether the chosen behavior preserves reviewed text or treats the incoming file as authoritative.
Write the result into the runbook, including the risk of overwriting approved material. For urgent corrections, use a controlled exception rather than permanently configuring broad replacement. Conflict settings are part of governance because they decide whose words users will eventually read.
20. Handle edit-unit operations carefully
Directly updating a translation unit can be useful for a targeted correction, but it bypasses some of the natural visibility created by reviewing a full language file. Record the string identity, intended locale, explanation, previous wording and person responsible. A unit-level API update needs the same editorial discipline as a change made through the web interface.
Suppose a support team identifies an incorrect label on a subscription cancellation button. The right correction must reflect the actual consequence of clicking. A technically successful edit that substitutes a friendlier but less precise verb can make the product more misleading.
Verify the updated unit in its surrounding interface, check placeholders, and make sure the server’s review state reflects the process actually performed. Do not present an API edit as approved if no qualified reviewer examined it. Keep a link or traceable reference to the decision where feasible.
21. Decide when locks are appropriate
The wlc command set includes locking and unlocking operations. A lock can support a coordinated freeze or prevent changes during a sensitive operation, but it can also block legitimate translation work. Treat locking as a release-management choice with a clear reason, owner and duration.
If a release branch is frozen for testing, communicate that status to translators. A sudden unexplained lock may encourage people to work offline or make changes in a different branch, creating more reconciliation later. A freeze must define what constitutes an emergency correction.
Before locking, inspect which scope the command affects and who can unlock it. Record the procedure for restoring normal collaboration. Use a lock only where its actual server behavior matches the intended control. It should supplement, not replace, a version-pinned release artifact.
22. Read statistics alongside work queues
Translation statistics can help allocate review attention, but no single number explains whether customers can perform important tasks. A locale may be mostly complete while its remaining gaps include consent wording or account-recovery messages. Another locale may show slower progress because a large optional documentation component is unfinished.
Compare translation counts and review states with the list of high-risk strings for the release. Ask whether a source change has invalidated an earlier approved message. A statistically complete project can still contain a new ambiguity that requires human interpretation.
Share actionable reports naming component, locale, source revision and specific outstanding decisions. Avoid turning progress measures into pressure to approve uncertain text. A useful dashboard helps people prioritize work; it does not replace language expertise or software testing.
23. Recover from source changes mid-review
Source edits are common while a product is being built. The problem becomes serious when reviewers approve translated text without seeing that the source now describes a different action. Establish how Weblate updates units from the repository, how uncertainty is marked, and how reviewers are notified about consequential changes.
A billing screen originally says Save card and later says Save card and charge now. An old translation that omits the charge could be dangerous even if its grammar remains excellent. Similarity between texts must not mask a change in commitment.
Test the lifecycle of a source edit in a sandbox component and observe status and history. Prioritize changed strings by meaning, not only edit distance. For material changes, request renewed approval and check the application interaction before deployment.
24. Trace the component to its exact source revision
When localization comes from Git, a filename alone may not establish which code version the translation matches. Record the repository URL, target branch, revision and Weblate component identity. This evidence helps differentiate an actual mistranslation from a correct string loaded into the wrong product version.
During a hotfix, do not download an active development component into a stable release merely because the filenames match. Compare affected keys, variable names and rendered actions. A stable branch may lack the feature that a new translation assumes exists.
Create a release manifest that binds source and language artifacts to an application build. Keep it alongside the release record rather than relying on the current state of a server. Incident response depends on reconstructing what was shipped, not just inspecting what exists now.
25. Make an accessibility review part of translation
Localization affects screen readers, keyboard access, labels and instructional clarity. A visible button text might be correct while the accessibility name remains in the source language. Another translation might introduce directional punctuation that changes the spoken order of an account number.
Exercise the actual interface with assistive technology in representative locales. Check headings, form labels, error associations, focus order and dynamic announcements. Reviewers should understand what a user hears as well as what a sighted reader sees.
Treat accessibility failures as product defects rather than asking translators to compensate with unnatural wording. Document the affected component and test procedure. Good multilingual accessibility requires engineers, accessibility specialists and language reviewers to cooperate.
26. Diagnose encoding and normalization defects
An exported file can parse correctly yet display unexpected characters because a downstream system assumes a different encoding or font. Investigate each layer instead of replacing the translation by guesswork. Compare the string as it exists in Weblate, its downloaded bytes and the application’s rendered value.
Check combining accents, nonbreaking spaces, Arabic bidirectional sequences, Japanese punctuation, emoji and filenames with non-ASCII characters where relevant. Visually identical sequences may have different code points, which matters when software uses exact identifiers or fragile text comparisons.
Keep the distinction between natural-language normalization and protected identifiers. Do not rewrite URL tokens, hash values or message keys casually. When diagnosing a bug, record both the visible symptom and the encoding representation so engineers can reproduce it.
27. Keep formal terminology decisions traceable
Glossaries help with consistency, but a repeated term may be wrong when reused in another context. The phrase account may describe a user login, a financial ledger or a contractual relationship. Review the surrounding action before adopting an old translation memory match.
A product renames teams to workspaces and updates its menu. Older strings remain in notifications and help articles, so customers now see two names for one feature. A terminology change should identify affected components and include a language-specific transition plan.
Record approved terms, prohibited alternatives where appropriate and context examples. Treat translations as living product text. Review terminology changes with people who understand the product and the market, not only the spelling of individual words.
28. Handle sensitive and confidential strings responsibly
Some source text can contain unreleased product details, internal links or private customer-specific examples. The synchronization workflow should avoid uploading secrets or personal information into translation files. Even a development fixture may contain credentials if the repository’s file glob is too broad.
Inspect source mappings and representative files before upload. Replace customer identifiers with clearly marked synthetic examples and avoid including real names merely to demonstrate placeholders. For security-sensitive wording, reviewers may need controlled access and additional confidentiality obligations.
Limit API permissions, protect exports, and keep sensitive material out of public build artifacts. A localization service is an important business system; use the same data-governance discipline that applies to code repositories and other external processing platforms.
29. Test a realistic repository-to-product cycle
Consider a multilingual help application that introduces a password reset waiting period. Engineers edit the source message, commit it on a release branch, and allow the Weblate component to receive the change through its configured repository integration. Reviewers translate the new message with context explaining the delay.
The release job checks component state, retrieves the intended locale files, parses them and verifies exact variables such as a duration. The interface is then tested with several time values and with screen-reader output. The team checks that the translation does not imply a different security policy.
After approval, the exact exported artifacts are committed or pinned according to the project’s build architecture. Support can identify which app version contains the message. This example illustrates why repository revision, human review and real interface testing must remain connected.
30. Troubleshoot from the narrowest failing layer
If the client cannot connect, inspect the API endpoint, network trust and authentication without exposing tokens. If the component is missing, check project names and permission scope. If the repository cannot synchronize, examine branches and integration settings. If a file downloads incorrectly, inspect format and export behavior.
A translation that renders with a wrong placeholder needs runtime and format investigation, not merely another network retry. A button with correct syntax but wrong meaning needs context and language review. Classifying the failure avoids sending every problem to the same person.
Prepare a minimal reproducible case with sanitized configuration, client and server versions, component identity, operation, expected result and observed behavior. Preserve before-and-after artifacts if a write occurred. Fix the cause, then add a regression check that specifically detects a recurrence.
31. Prepare a release rollback
Before publishing multilingual content, keep a known-good translation artifact associated with the last working application build. If a serious language defect appears, restoring the previous artifact may be safer than editing multiple unrelated messages under pressure. But a prior file must still match the current application schema.
Test restoration in a safe environment. Verify keys, variables and product version compatibility. Record whether rollback requires a new application build, a content deployment or a Weblate-side correction. The procedure should distinguish the immediate customer fix from the deeper investigation.
Do not erase evidence of a wrong translation merely because it was corrected. Retain the source revision and correction rationale so reviewers can learn from the incident and avoid repeating the same ambiguity in another language or component.
32. A complete Weblate wlc release checklist
Start with a trusted API endpoint, least-privilege credential and known client version. Confirm project, component, branch, file formats and source revision. Separate inspection, upload, approval, server-side repository operations and export. Test conflict behavior and any release lock in advance.
Before shipping, compare translated and approved states with the actual critical message set. Inspect the download diff, parse the resource format, test variables and plurals, and render the interface in representative languages and devices. Include right-to-left, mixed-script and accessibility checks as needed.
Record the artifact hashes, repository revision, language sign-off and accepted exceptions. Monitor product feedback and preserve a recovery route. Weblate wlc is most valuable when it makes an accountable translation process observable, not when it merely replaces the web interface with a terminal command.
Frequently asked questions
Is wlc a replacement for Weblate?
No. It is a command-line client for interacting with a Weblate instance via its REST API. Human translators and project administrators still need the collaborative service and its workflows.
Where should we store wlc credentials?
Use secure environment or configuration mechanisms with appropriate permissions. The official client documents WLC_KEY and key options. Avoid recording secrets in repository files or public logs.
Do uploads always overwrite translations?
No single assumption is safe. The upload method and conflict behavior determine how incoming content is treated. Test the selected settings, especially where approved text could be replaced.
What is the difference between translated and approved?
Those are distinct workflow states. Project policy should define who can approve and what review evidence is needed; neither state independently proves correct rendering or meaning.
Can we safely download everything before a release?
Only when the scope, component list, readiness and output destination are understood. Isolated exports and reviewed diffs reduce accidental inclusion of unfinished content.
Does repository push mean the language is ready?
No. A push is a version-control operation. Shipping readiness requires linguistic and technical review and a compatible application build.
Why does a correct string look broken in the UI?
The cause may be font coverage, directionality, escaping, truncation, formatter behavior or application context. Examine the path from server text to runtime rendering.
What should a support report contain?
Include sanitized client configuration, tool and server versions, component, locale, command, expected result, actual output and whether data changed. Never include tokens or private user data.
Official documentation and next reading
Confirm syntax against the Weblate Client documentation and the Weblate Client project. These sources explain installation, configuration, supported commands, upload methods and security boundaries. Version-specific behavior and hosted-instance permissions may differ, so test planned writes on a safe component first.