Skip to content

Instantly share code, notes, and snippets.

@infocynic

infocynic/TranslationFun.md

Created October 11, 2022 13:25
Show Gist options
  • Save infocynic/225b6950c1d760e7936ca98f9643ee13 to your computer and use it in GitHub Desktop.
Save infocynic/225b6950c1d760e7936ca98f9643ee13 to your computer and use it in GitHub Desktop.
Download ZIP
Salesforce translations
Raw
TranslationFun.md

Translations

Fair warning: Translations in Salesforce are painful. This is the least bad option I could find and I spent 4 hours working on this in May 2020. -InfoCynic

A word to admins and devs

Please avoid putting special characters or commas into the API names of picklist values. If you make a picklist value that has special characters, please edit it afterward to change the API name to something safer. This will greatly reduce the time it takes to make working translation files.

Software required

Microsoft Excel Any text editor capable of changing the file encoding; e.g. Notepad++

Overview

  1. Export an STF file
  2. Import the STF using Excel's Get Data From Text wizard
  3. Save as an Excel file and Translate
  4. Export a tab-separated file from Excel
  5. Import the file into Salesforce
  6. Correct errors and reimport until successful

Export an STF

It is recommended to do this in a stable environment or only do small chunks at a time, taking a fresh export after each. Any destructive changes to the environment (removing / renaming API names of things) will break the import.

  1. From Setup search Translation and click Export.
  2. Select Outdated and Untranslated and then Export STF. If you are doing a major new translation for a new region that has minimal prior work done, selecting Bilingual will be better. There are slightly different instructions below for bilingual.
  3. Wait for Email
  4. When email arrives, use the link to go to the documents page (this will use Classic, that's OK).
  5. Likely there will be multiple parts, so repeat for each part: Click the filename, then find the somewhat obscure "View File" link to download the ZIP file
  6. When you have all the ZIPs, open each one to find the one with the language(s) you want to translate, extract those files to anywhere you can easily find, such as your desktop
  7. You can delete the ZIPs afterward along with any extracted languages you don't need

Import the STF into Excel

Always start from a blank workbook. Never open the file directly in Excel; only use the Data Import Wizard.

  1. From a blank workbook, click Data -> From Text/CSV
  2. Browse to your file (change to show All Files) that you extracted from the ZIP (choose only one language here; you can repeat this step for more languages later)
  3. Under File Origin, select 65001 Unicode UTF-8. Failure to do this will corrupt some special characters.
  4. Ensure Delimiter is set to tab, and Data Type Detection is Based on first 200 rows.
  5. Click the drop-down next to Load and select Load To...
  6. Select Existing worksheet
  7. Click OK

Save as an Excel file and Translate

  1. Change the labels from Column1, Column2 to #KEY and LABEL (you may copy Row 16 or thereabouts)
  2. Use the Save As menu to Save the Excel file anywhere convenient (e.g. OneDrive if you want to share with multiple translators)
  3. DO NOT CHANGE COLUMN A.
  4. The text in column B is the English text; simply replace this with what you want the translated text to be. (If you want to preserve the original, you may copy it into Column C; but if you do this, you must completely delete Column C before you Export later.) Bilingual export: You will place your translation into Column C; leave column A and B alone.
  5. You may use filters on Column A to help find what you're looking for; e.g. if you need to translate something related to a particular object, try filtering Column A with the object's API name.
  6. If you are a business admin sharing this file with a team of translators, you may want to use filters and your knowledge of what sections of the system your business group uses to delete rows that do not need translations.
  7. Leave the English text untouched or delete the entire row to skip translating that item. If you delete, always be sure to delete the entire row.
  8. Save your work frequently or use auto-save.
  9. When finished, if you created a column C, be sure you delete it now.

Export tab-delimited file

These steps require the desktop version of Excel and will not work on the Web client.

  1. In Excel, click File -> Export (NOT Save As)
  2. Click Change File Type and select Text (Tab delimited), then click Save As
  3. Browse to a convenient location like your Desktop and give the file a name like "Salesforce MX Translate John Doe 2020-05-19 4pm.txt" (the date is highly recommended along with your name and the time; in case you submit multiple files in a day, it will be easier to read the error logs)
  4. Excel warns that it can only save data from the Active Sheet. Click OK.
  5. Close Excel after the export is complete.
  6. Using my documents/windows explorer/Finder/etc. locate the folder where you saved your file.
  7. Open the file in your advanced text editor (Notepad++, etc.)
  8. Under the Encoding menu, ensure that UTF-8 is selected (not UTF-8 BOM). If you made a change, save the file now.
  9. Close your text editor.
  10. Rename the file to have a .stf extension.

Import to Salesforce

Always import to the same environment you exported from. The longer period of time between the export and the import, the more errors you will be likely to have. Consider doing smaller export/import cycles.

  1. From Setup, search Translate, and click Import.
  2. Click "Choose File" and browse to find the STF file you exported in the previous step.
  3. Click Import
  4. Wait for Email

Review Error Logs

  1. Because Salesforce is extremely sensitive about these files, it will likely have errors. When the email comes, you will need to go to your documents folder in Salesforce and the email will NOT have a link. Look back in your email for the link that you got when you made an Export; that will take you to your documents folder.
  2. The top-most file should be the error log, it will be named something like log name-of-your-file.txt. Click that and then click the View File link to read the log.
  3. To correct these errors, you'll want to load your Excel file that you last saved, before you exported. If you are comfortable working in a text editor and can be very careful not to accidentally delete any tabs, you may do this directly in your advance text editor and save having to re-export the file, but it is safer to use your Excel copy.
  4. Types of errors and their resolutions:
    1. Invalid key: "XYZ.ABC": Copy most of the invalid key and CTRL-F to find it in your document. Delete the entire line. You will not be able to translate this via import; you will have to use Translation Workbench.
    2. Salesforce cannot make this key for your Custom Report Type column unique:CrtColumn.Blah.Blah.Blah: same as previous error.
    3. Duplicate key: Something.SomethingElse.StillMore: same as previous 2 errors.
    4. Error parsing XML: lineNumber: 1234; columnNumber: 56; Invalid byte 2 of 3-byte UTF-8 sequence. : Go to that line number and look carefully for any special characters; if they are in the KEY (Column A), you have to deleted the line. If there are special characters in the LABEL (column B) you can try to edit and remove the special characters. (If it fails a second time just delete the line; it's not worth fighting.)
    5. Error parsing XML: lineNumber: 13087; columnNumber: 78; Character reference "&#55357" is an invalid XML character.,: Yell at the HR Admins who put special characters into their picklists, then delete the row(s).
    6. Wrong number of columns in line: ButtonOrLink.MC4SF__MC_Campaign__c.MC4SF__Refresh_Campaign_Stats. Check that you have escaped tabs (\t), new lines (\n) and carriage returns (\r) in your files.,: You probably forgot to delete any extra columns. Go back to Excel, highlight Column C through Z, and use the menu to completely delete those columns. Re-export and try again (doing this once will fix any number of lines that report this error). If the problem persists, be sure that there is NOTHING, not a space, not a highlight, nothing at all, and that you have completely DELETED the columns before you export. It is not good enough to just delete the contents of the cells; you must delete the entire COLUMNS.
    7. Missing translation for: PicklistValue.VisualAntidote__Staging_Submission__c.VisualAntidote__Batch_Status.Processed: You have to put something in the line to translate it, or delete it. You can leave the English text untouched or delete it, but don't just delete the LABEL without deleting the entire row.
    8. No valid file type specified in file header.: Double-check that the file is saved as UTF-8 and that around line 12 there is a pattern like Language code: es_MX

Lather, rinse, repeat

  1. After fixing all the errors you can find, Save your Excel copy again.
  2. Repeat the previous steps to export the Tab-separated file, ensure it's UTF-8, rename it, upload it, and check the logs.
  3. A good sign is if you don't get an error email after about 1 minute; it's probably working on the file and will notify you in a while when it's done.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment