Best Practices for Working with Translations

Observe the following recommendations to prevent translation string issues in your translated versions of the NetSuite application. These recommendations also contain practical examples of behavior you might encounter when using NetSuite.


These best practices apply to translation strings in Suitescripts, saved searches, custom reports, web services integrations and other customizations.

Use IDs instead of UI Labels in References

In your customizations, do not use references to UI labels. Instead, you should use IDs in references. An ID is a static internal value of an object, it is always unique and it generally does not change. If you use custom features such as:

  • Implementation guides

  • user manuals

  • automations using SuiteScript

  • customizations

  • scripts

  • reports

  • searches

  • integrations

  • any other solutions utilizing UI labels,

avoid prospective changes proactively and replace the UI labels with static ID values. Because IDs do not change, it is safer to use them in references than UI labels, which can change due to variations in translations. For example, if you refer to a specific UI label and either the label itself or its translation changes, the reference is no longer valid, and any customizations containing this reference no longer work.

For information on how to display IDs, see Showing Record and Field IDs in Your Account.

If an ID cannot be used or found, for a temporary fix, you can replace the old translated term in the label with the new translated term provided in the list of changes. Please note that this should not be considered a permanent solution. You should replace the label with an ID value as soon as possible. Contact NetSuite Customer Support for assistance with a missing or unusable ID.

See the table below for examples of updates made to the en-GB locale.


Old Value

New Value

Field Label

Address ZIP Code

Address postcode

Record Name

Payment Gateway Plugin

Payment gateway plug-in

Record Name



Record Name

Mail Template

Email template

Drop-down Value

Real Estate


Alert Message

You must set inventory details for all Assembly Builds to be generated.

You need to set inventory details for all assembly builds to be generated.

Error Message

Comparison reports cannot be customized in the Classic Report Composer. <p>To customize this report, you must first go to Home > Set Preferences > Reporting subtab and disable the Use Classic Report Composer preference.

Comparison reports cannot be customised in the Classic Report Composer. <p>To customise this report, you must first go to Home > Set Preferences > Reporting subtab and disable the Use Classic Report Composer preference.

Button Label

Print Voucher

Print discount code

Menu Item

Set Up States/Provinces/Counties

Set Up counties/regions

Translated Role Title

An American client uses an ”Administrator Role” to verify authorization of a script. Imagine that a client’s French employee tries to use the script. Since they are using the NetSuite application in French, the ”Administrator Role” has been translated to French and now it shows “Rôle d'administrateur”. However, since the script is looking specifically for the UI label ”Administrator Role”, it does not recognize the role and it does not permit deployment of the script. If the script used a reference to an ID, a unique system value, instead of a UI label ”Administrator Role”, the script would work without any problems.

Altered Document Status

A report refers to a document status ”Completed”. Imagine that for some reason, a client decides to rename the ”Completed” status to ”Done”. Because the document no longer displays the required document status, the report does not recognize it and does not work with this document. If the report used a reference to an ID, a unique system value, instead of a UI label “Completed”, the report would display without any problems.

Opt in to Release Preview

Before each NetSuite release upgrade, opt in to access a Release Preview account as soon as it is available and test your customizations to make sure that they are functioning correctly. If they are not, contact NetSuite Customer Support.

The Release Preview account enables you to become familiar with the new features in an upcoming release.

For more information about Release Preview accounts, see Overview of Release Preview.

Related Topics:

Translatability Support
Translatability Overview
Translation Management
SuiteApp Translatability Support
List of Topics

General Notices