When localizing content, you can set up localization directly within Builder or you can integrate with Smartling. With Smartling you can connect with multiple projects.
To use the Smartling integration, you need:
- A Smartling account with a project
- An app integrated with Builder
- Admin access to your Builder Organization
To connect Builder with Smartling:
- From your Smartling dashboard, go to Account Settings > API.
- In the Account Tokens section, click Create Token. Account tokens enable connection to multiple projects.
- Name your token and click Create.
- When the success message displays, copy the Account UID, the User ID, and the Token Secret.
The following image is a screenshot of the API page with the info you need for Builder.
Important: The Token Secret is only visible immediately after creation. Copy it before closing the dialog.
For more information on Smartling API Tokens, refer to Introduction to Integrating Smartling.
With the Smartling API page still open, go to Builder in another tab.
- In Builder, go to the Integrations page.
- Click the Advanced button at the top-right of the page.
- Select Advanced Configuration.
- In the dialogue that opens, click Add Plugin and enter
@builder.io/plugin-smartling. - Click Save.
- When the page reloads and prompts you to continue, click OK.
- Click the Configure button within the Smartling integration card.
- In the dialogue that opens, enter your AccountUID, your User ID, and the Token Secret.
- Click Save Plugin Settings.
The following video demonstrates this process:
After connecting your Smartling account, you can configure additional settings:
| Setting | Description |
|---|---|
Default project | Set a default Smartling project that auto-populates when creating new translation jobs. Users can override this on a per-job basis. |
Auto-authorize jobs | When enabled, translation jobs are automatically authorized in Smartling upon publishing from Builder. When disabled, jobs are sent to Smartling but require manual authorization. |
Copy Smartling locales | When enabled, locales from your Smartling projects are automatically synced to Builder's custom targeting attributes. |
Enable visual context capture | When enabled, Builder automatically captures screenshots of your content and uploads them to Smartling as visual context for translators. |
Note that the Token Secret field is masked in the UI to protect your credentials.
The Smartling integration can automatically capture and upload visual context screenshots to help translators understand how text appears in your content.
This setting works as follows:
- When you authorize a translation job, Builder captures screenshots of your content.
- Screenshots are uploaded to Smartling as visual context.
- Smartling's OCR matches the screenshots to the translatable strings.
- Translators see the visual context alongside the strings they're translating.
Once configured, create and manage your translation jobs by leveraging tools in both Builder and Smartling.
To create a new translation job:
- Publish your content.
- Click the three-dot menu in the top-right corner.
- Select Add to translation job.
- Click the + Create button.
- Enter a name for your new translation job.
- Click the OK button.
This process creates a new Translation job data entry within Builder. To enact your job, it must be authorized.
To authorize your job:
- Click the Go to Job Details button that appears after creating a new translation job. Alternatively, click the three-dot menu and select View translation job.
- If a Smartling Project has not already been chosen, select a Project from the Job details section.
- Select one or more locales under the Target Locales section.
- Click Authorize.
When you click Authorize, Builder writes the entries to JSON files and sends them along with the instructions and job description to the project with the target locales. When the process is complete, Builder generates a notification.
Once complete, translation jobs are applied to your content entry.
To create a new translation job:
- After making changes to your content, click the Publish button.
- Click the three-dot menu in the top-right corner.
- Select Add to translation job.
- Select an existing job.
Follow the authorization process to send your translation job to Smartling.
To manually exclude a text block from translation:
- Right-click on the text block.
- Scroll down the menu options and select Exclude from future translations.
Keep in mind that this option maintains current translations. Exclusion only applies to future translations.
To delete a translation job:
- Click the three-dot menu in the top-right corner.
- Select View translation job.
- Click the three-dot menu in the top-right corner.
- Choose Delete.
Deletions are synchronized bidirectionally:
- Jobs deleted in Builder are also deleted in Smartling.
- Jobs deleted or canceled in Smartling are reflected in Builder.
Content entries are automatically updated to remove translation status when their associated job is deleted.
Builder's Smartling integration supports Variant Containers, allowing you to translate personalized content variants.
To translate a Variant Container, no special process is needed. Create your variant with adjusted text, click the Publish button, and then create or add a translation job.
When you send content with Variant Containers to Smartling:
- Everything outside of the Variant Containers are sent as one file.
- Each variant is sent as a separate file.
- Translations are applied independently to each variant based on its target locales.
This ensures that:
- Personalized content variations are properly translated
- Each variant can have its own set of target locales
- Translations don't interfere with other variants
Below are fixes for some of the most common issues experienced when utilizing the Smartling integration.
If a translation job shows "in progress" but the associated Smartling job was cancelled or deleted, the status should automatically update. If not:
- Check the job status in Smartling directly using View Job in Smartling.
- If the job was deleted, remove the content entry from the Builder job and re-add it to a new job.
If content is not appearing within Smartling, ensure that:
- The content is published before adding to a translation job.
- The translation job has been authorized and not just saved as a draft.
- The Smartling project type is one of the supported file types.
If certain strings are missing from your Smartling job:
- Check if the text block was excluded from translation.
- For symbols, ensure you're not seeing placeholder text.
- For nested symbols, ensure the integration can access the symbol content.
If screenshots aren't appearing in Smartling:
- Verify that visual context capture is enabled in plugin settings.
- Ensure the content has a valid preview URL.
- Check that the content can be rendered. JavaScript errors prevent screenshot capture.
For more information on localization in Builder, check out the documentation on Localization with Builder.