Strings

Strings let your application support the language preferences of users.

They are stored in .string files as string id/value pairs, for example:

ids.name=Name
ids.description=Description

When the model references a string id, it is replaced with the appropriate text from the .string file at load or runtime.

The choice of the description value is based on the language of the current user, such as English or Spanish. There are separate string files for each implemented language. String files are found in the meta/strings folder and are named <fileName>.<language_code>.string. For example:

• meta/strings/inform/Subscription.meta.en.string
• meta/strings/inform/Subscription.meta.fr.string
• meta/strings/inform/Subscription.meta.es.string

The Subscription.meta.es.string file stores the strings in Spanish. The English strings in the previous example would be stored in Spanish as the following:

ids.name=Nombre
ids.description=Descripción

At runtime, if the user's language is set to Spanish (es), then the properties of the Subscription.class.es.string file are compared against stringId references in the model. They are then displayed appropriately in the user interface, error messages, or reports.

To use a string, simply reference it in your model properties or script. For example:

<Column caption="ids.name" event="sysDetail" length="100" name="colName" values="name"/>

The system substitutes the appropriate translated value (for example, "Name") when displaying content to the user. Most UI properties support stringIds.

String naming standards

The following format for naming and storing strings and string files is used for clarity and to avoid collisions. 

This standard was introduced in August 2021. Any existing strings that we previously used will continue to work.

Tooling doesn't currently support this standard by default, so the standard needs to be implemented manually.  

Follow these naming conventions:

• Where applicable, always namespace strings created in your model.
• Use component-specific string naming if needed. For example, inform.finance.Admin.portal.caption=Admin Portal.
• Use practical simple naming for reuse within your model when possible. For example, tenant.Subscription=Subscription.
• You may reuse common strings in your model, such as ids.name or ids.description.

Prior to implementing the standard, a string name had the following format: ids<componentTypeLetter>.<componentName>.<stringName>=<value> For example, idsa.Admin.caption=Admin Portal.

Following the standard, this string would be named in the following format: <dot-separated-namespaces>.<componentName>.<componentType>.<stringName>=<value> For example, inform.Admin.portal.caption=Admin Portal.

Background

Namespaces may be global within a model by setting its "module" property. That means all component names within the model will be prefixed with "module". Namespaces are hierarchical and are separated by ":". In our examples, we will use the  module="inform:finance".  Namespaces may be added to components as well by putting them in folders, so a component in a folder called "ui" would end up with a namespace of "inform:finance:ui".

Components have a component name and a type. For example, for the Contact.portal component, the component name is Contact and the component type is portal. The full component name is based on the following format: <optional-namepace1>:<optional-namespace...>:<optional-namespaceN>:<componentName>.<componentType>. For example, inform:finance:Contact.portal.

The location for this component's metadata is based on the following format: <model>/meta/<componentType-plural>/<optional-namespace-folders>/<componentName>.<componentType>. For example, /meta/portals/inform/finance/Contact.portal.

If the model has a module, the physical folders in the module namespace are omitted from the storage locations. For example, if the model module is "inform" in the example above, then the file is stored in <model>/meta/portals/finance/Contact.portal. If the model module was "inform:finance", then the file would be stored in <model>/meta/portals/Contact.portal

String naming details

Namespaces

Since models are often mixed together, not using namespaces can cause collisions. For instance, an ids.name string defined in a mixin model may cause side effects by overriding the ids.name string from the enterprise or finance model. Therefore, stringIds must be preceded with dot-separated namespace names from the module that contains the string, as well as the target components which use the string. In the example above, all strings in the inform module should be prefixed with inform.finance. In addition, any strings pertaining to components in the ui folder should be prefixed with inform.finance.ui.

String names

When naming strings, strive for a balance of consistency and practicality. 

Consistent component-specific string naming

Strings associated with the component are formatted as: <dot-separated-namespaces>.<componentName>.<componentType>.<stringName>=<value>

The first word after the namespace should be capitalized. This is usually the componentName in component specific naming. The componentType value is derived from the filename extension of the type of component, such as .portal or .layout.

For example:

inform.finance.Admin.portal.caption=Admin Portal
inform.finance.Articles.layout.pageNext=Turn to the next page
inform.finance.Article.class.caption=Article

When the filename extension is .meta, use class rather than meta as the componentType value. For example, inform.finance.Article.class.Caption=Article.

Practical exceptions

You can define higher-level stringIds for strings you know will often be used in your module. For example, tenant.Tenant=Tenant or tenant.Tenant.clientSecret=Client Secret. If you expect to use Client Secret without change in multiple contexts, then you can also use tenant.ClientSecret=Client Secret. If required, you could create a more component-specific string later.

You can reuse common "global" strings. These are static strings, with values such as "name", "description", and "date".  They are typically defined in core, enterprise, or other base models. Reusing these strings avoids redefining (and re-translating) the same string multiple times. If there is a special case where the common term isn't appropriate, you can override it with a local string. For example, use ids.name for most instances of the word "name" in your application, but define a new inform.finance.class.Article.name string if the article name in the inform model needs to use a different term, such as "title".

File names and locations

As long as the strings are in a .strings file in the meta/strings folder, they will be picked up.  

If the strings are specific to a component, then they should be stored in a component-specific file.  This helps during model refactoring, if needed. Strings associated with the component are stored in the <model>/meta/strings/<optional-namespace-folders>/<componentName>.<componentType>.<language>.strings file.  For example, the English strings for the Contact.portal component in the inform namespace are stored in the  <model>/meta/strings/inform/finance/Contact.portal.en.strings file. The equivalent French strings are in the Contact.portal.fr.strings file.

The componentName and componentType are optional in the folder name, similarly to the optional namespace. If no componentType is used when creating the string, then optional parts after the name will be used for the filename.

File name and location examples

Tooling

Select String dialog

To enter a value for a property with type string, click the Select button in the field. The Select String dialog appears. In this dialog, you can search for existing strings or create new ones. Based on the string names you provide, NexJ Studio will automatically create a new file for your strings.

Strings Tool

To support translation of strings, the Strings Tool allows you to import and export strings to send to a translator. For convenience when exporting, strings from multiple files are combined into a single file. When the translated file is received back from the translator, the importing command updates the appropriate files in your model with the changes.

The Strings Tool is found at Run > Run Tool > Strings Tool and is also available on the toolbar.