Salesforce Integration Guide

This guide explains how Lingora connects to Salesforce, how to set up and authorize a connection, and how to retrieve and deploy metadata directly from your org.

---

Two Modes of Operation

Lingora supports two ways to work with Salesforce translation files depending on your tier and preferences.

Mode 1 — Upload-Based (All Tiers)

No Salesforce connection required. This mode works for any Lingora tier.

1. Export XLIFF or STF files manually from Salesforce Translation Workbench (Setup > Translation Workbench > Export).
2. Upload the exported files to a Lingora project.
3. Translate and review using Lingora's workspace.
4. Download the translated files from Lingora.
5. Import the translated files back into Translation Workbench (Setup > Translation Workbench > Import).

This mode gives you full translation capability without granting Lingora any access to your Salesforce org.

Mode 2 — Connected App (Studio & Partner Tiers)

Lingora connects directly to your Salesforce org via OAuth 2.0 and uses two APIs:

• Metadata API (SOAP) — retrieve and deploy translatable metadata (Custom Labels, Fields, Flows, etc.)
• REST API — query and write-back Knowledge Article translations (__kav records)

Key capabilities:

• Retrieve translatable metadata automatically — no manual export required
• Deploy approved translations directly back to your org — no file handling required
• Knowledge Articles — query published and draft articles, translate rich text HTML fields, and write back as draft translations
• Supports sandbox and production orgs

The rest of this guide covers Mode 2 setup and usage. For Knowledge Article-specific workflows, see the Knowledge Articles guide.

---

Setting Up a Connected App in Salesforce

Before connecting Lingora to your org, you need to create a Connected App in Salesforce. This gives Lingora a set of OAuth credentials it uses to request authorization.

Prerequisites: You need Salesforce admin access.

Step-by-step

1. Log into Salesforce Setup (click the gear icon > Setup).

2. Navigate to Platform Tools > Apps > App Manager. On newer orgs, this may appear as External Client Apps.

3. Click New Connected App (or New External Client App).

4. Fill in the required fields:

   Field	Value
   Connected App Name	Lingora Translation
   API Name	Lingora_Translation
   Contact Email	Your email address

5. Scroll to the API (Enable OAuth Settings) section:

   • Check Enable OAuth Settings.
   • Callback URL: Copy the callback URL from Lingora's Settings page. It will be displayed there in the Salesforce Connection section. The format is: https://your-lingora-domain/api/salesforce/callback
   • Selected OAuth Scopes: Add the following two scopes:
     • Access and manage your data (api)
     • Perform requests on your behalf at any time (refresh_token, offline_access)

6. Click Save. Salesforce may take a few minutes to activate the Connected App.

7. Once saved, open the Connected App and copy the Consumer Key and Consumer Secret. You will enter these in Lingora.

Newer Salesforce orgs: The App Manager interface has changed in some org editions. If you see "External Client Apps" instead of "App Manager", the same OAuth fields are present — the navigation path is slightly different.

---

Required Salesforce User Permissions

The Salesforce user who authorizes the connection must have the following permissions. Lingora displays a checklist of these requirements in the connection UI before you begin authorization.

If any of these are missing, the OAuth flow will succeed but subsequent retrieve or deploy calls will fail with an insufficient privileges error.

---

Connecting Lingora to Salesforce

Click-path: Sidebar > Settings > Salesforce Connection section

1. Enter your Connected App's Consumer Key and Consumer Secret in the corresponding fields.
2. Toggle Sandbox if you are connecting to a sandbox org (test.salesforce.com). Leave it off for production orgs (login.salesforce.com).
3. Click Connect to Salesforce.
4. You will be redirected to the Salesforce login page. Log in with an account that has the required permissions listed above.
5. Review the OAuth permission screen and click Allow.
6. You will be redirected back to Lingora Settings. The connection status changes to Active and your Salesforce instance URL is displayed.

At this point, Lingora holds encrypted OAuth tokens for your org. The tokens are AES-256 encrypted at rest and are never exposed in the UI, logs, or API responses.

---

Retrieving Metadata

Click-path: Projects > select a project > Retrieve from Salesforce

Retrieval pulls translatable metadata from your Salesforce org and converts it into translation bundles inside your Lingora project.

What happens during retrieval:

1. Lingora builds a metadata package manifest listing the types to retrieve.
2. It calls metadata.retrieve() via the Salesforce Metadata API. This is an asynchronous Salesforce operation.
3. Retrieve progress is shown in the Job Monitor. Large orgs may take several minutes.
4. Once complete, Lingora downloads and parses the retrieved ZIP, creating translation bundles identical to those produced by a manual file upload.

Supported metadata types:

Incremental retrieval: If you run retrieval again after translating some units, Lingora merges the new metadata with existing bundles. Already-approved translations are preserved.

---

Deploying Translations

Click-path: Projects > select a project > Export > Deploy to Salesforce

Deployment pushes your approved translations back to Salesforce as metadata, replacing the source strings with translated equivalents.

What happens during deployment:

1. Lingora assembles all approved translation units into Salesforce metadata XML, using the correct file structure for each metadata type.
2. It creates a deployment ZIP with the directory layout Salesforce expects.
3. It calls metadata.deploy() with rollbackOnError: true — if any component fails, the entire deployment is rolled back. No partial deploys.
4. The deploy job runs asynchronously. Monitor progress in the Job Monitor.
5. When complete, the results view shows:
   • Success count
   • Failure count
   • Error details for any rejected components (component name, error message, line number where applicable)

Always test in a sandbox first. Deploy to your sandbox org before deploying to production. If errors appear, fix the flagged translation strings and redeploy.

---

Known Limitations

---

Troubleshooting

---

Tips

• Always start with a sandbox. Validate your translations in a sandbox org before deploying to production. Rollback is automatic on failure, but a clean test run is faster than diagnosing deploy errors.
• Monitor the Job Monitor. Both retrieve and deploy operations are asynchronous. Check the Job Monitor (Sidebar > Jobs) rather than waiting on the export screen.
• Keep Consumer Key and Secret secure. These credentials grant OAuth access to your Salesforce org. Do not commit them to version control or share them outside your team.
• Reconnecting does not lose data. If your connection expires, reconnecting on the Settings page restores API access without affecting your existing projects, translations, or Translation Memory.
• Token-containing strings are protected. Salesforce merge fields ({!...}), format tokens ({0}, {1}), and HTML tags are automatically protected during translation. They are replaced with safe placeholders before any engine call and restored in the final output.

---

Related Guides

• Getting Started
• Settings & Engine Configuration
• Export & Deployment
• Partner & Multi-Org Management