By default, in Application Resource Files projects, strings in each file are treated as unique by Smartling. This means that uploading a new file will create new strings in the dashboard, even if they have the same text as strings in other files. This way, you can still leverage your existing translations using SmartMatch, but you also have the freedom to translate a string differently if you need to.
Sometimes, however, you may want strings to be shared between files, such as when you replace an existing file with an updated version of the same file with only a few strings changed, and you don’t want to create a whole new set of strings. You can allow files to share strings by giving them the same namespace.
By default, the namespace of a file is its URI, which is usually the file path/name. When using the Smartling dashboard this is represented by the file name (e.g., Q1 conference handout EMEA.docx). When files are uploaded via API the URI is controlled by the API caller and can be anything, though usually, it will be the filename or a path with a filename (e.g., /src/code/en.json)
You can also assign a custom namespace to a file using the smartling.namespace API directive when you upload the file. You may wish to do this if your File URI contains version information, to avoid creating a full set of unique strings every time you update a file.
Example 1
You have integrated with the Smartling API to automatically upload files. Because you are uploading directly from your source code repository it will make sense to explicitly declare namespaces for files to avoid unnecessary repetitions of strings.
If you have a resource file that needs translation in the main of your repository: main/src/code/res/en.json
We recommend you set the namespace as the path to the file within the repository: /src/code/res/en.json
If you create a branch and make a change to en.json at branch1/src/code/res/en.json you can upload that specific version of the file to Smartling with the namespace /src/code/res/en.json and URI branch1/code/res/en.json. The strings that are shared among all versions of the file will not be duplicated, which avoids repetitions of the string. You will effectively have a version of the file that corresponds to the changes in branch1 and can authorize translation for the changes in that branch without affecting the version of that file in the main (or other branches). When you finalize all the changes in the branch (including string changes and their translations) and merge them into the main, the main version of the file is updated and will reflect all the latest translations without needing to go through the translation workflow again in Smartling. When that version of the file is sent to Smartling it should be fully translated because the strings were translated while the file was in the branch.
If you do not explicitly set namespaces, the default of using the file URI as the namespace applies. The result is either:
- Only one version of the file translated at a time.
- Repetitions of strings caused by the use of multiple unique URIs for what is effectively the same file.
Example 2
This is a simple example showing best practice using namespace from API integration:
file name: en.json
path: /src/code/res/
Smartling URI: /main/src/code/res/en.json
Smartling namespace: /src/code/res/en.json
Contents: { "string1key" : "string1 value"}
file name: en.json
path: /src/code/res/
Smartling URI: /branch1/src/code/res/en.json
Smartling namespace: /src/code/res/en.json
Contents: { "string1key" : "string1 value", "string2key" : "string2 value"}
There will be two unique files in Smartling, but they will share strings in a way that avoids repetitions.
For information on Namespace in GDN, read our article on Creating Unique Strings with Namespaces in the GDN.
Ask your Smartling CSM if you want to enable namespace behavior for an existing account.