setTranslationFiles for CCPA/USP
- Nelson Pina
- Reinhard Steiner
- 1 Functionality
- 2 Syntax
- 3 Description
- 3.1 Scope
- 4 Examples
Functionality
The setTranslationFiles function is used to provide customized text and translations for specific user languages in AdConsent. The translation file is chosen from the user’s browser language.
Syntax
function adconsent.gdpr()function adconsent.ccpa()
argument name | type | optional | value | description |
|---|---|---|---|---|
command | string |
|
|
|
parameter | object |
|
|
|
callback | function | ✔️ |
| The callback function that is called with the function call result. |
TranslationsSettings
TranslationsSettings = {
path: String,
locales: [<array of String>]
}TranslationsSettings.path
The path to the translation files. This location can be the publisher's own website or somewhere else on the internet. It should point to a folder where all the custom translations for this particular consent law API are located though. The translation files for a particular consent law API cannot be stored in different folders.
The translation files need to be in JSON format (check the structure for each consent law GUI below) and named after the 2-letter code for each country language the publisher wants to customize. So, e.g., a custom translation file for German should be named de.json, an English one should be named en.json, and so on.
TranslationsSettings.locales
This is an array holding the 2-letter code for each country language the publisher wants to customize their labels. Some of the possibilities include 'en', 'de', 'fr', 'pt', 'it' between others, and depend on the consent law we are configuring. Only languages with the corresponding custom translation files available should be added here. If that's not the case, when AdConsent tries to fetch the file it will fail and will default to the default translation for that GUI.
Valid locale options and customization for each consent zone
Each consent zone, or law, shows a different GUI to the user, allowing different levels of customization and even different levels of language support.
GDPR
GDPR allows customization for the following languages:
'cs'(Czech)'de'(German)'el'(Greek)'en'(English)'es'(Spanish)'fr'(French)'hr'(Croatian)'hu'(Hungarian)'it'(Italian)'nl'(Dutch)'pl'(Polish)'pt'(Portuguese)'sv'(Swedish)
Any user language outside of this set cannot be customized, and the GUI will show in its default language. To change the GUI default language, please check the setDefaultLocale function usage.
The GDPR GUI only allows to customize and translate a subset of text due to legal reasons, in order to guarantee the usage of certain terms in certain places. Customization supports the welcome title and welcome text in AdConsent using enableWelcomeText, along with the publisher consent tab label, description, and existing custom purposes that may have been set in the setPublisherPurposes function.
{
"welcomeTitle": "My custom welcome title",
"welcomeText": "My custom welcome text",
"publisherTitle": "My custom publisher tab title",
"publisherText": "<p>Custom Publisher text, allowing <a href='http://www.snigel.com' target='_blank'>links</a> and HTML in general<p>",
"customPurposes": [{
"id": 1,
"name": "Translation for custom purpose 1 name",
"description": "Translation for custom purpose 1 description",
"descriptionLegal": "Translation for custom purpose 1 legal description"
}]
}These files may have all the fields or only some of them. In this case, undefined fields will revert back to the original translation for them.
CCPA
CCPA doesn't limit wording, so the publisher may add any language to be supported and may change all the labels in it. The file structure is as follows:
{
"element": "My custom don't share my information button label",
"title": "My custom gui title",
"description": "My custom gui description, e.g., You, as a California resident, may exercise your consumer right to opt out of sharing or trade your personal information with 3rd party vendors.",
"notice": "My custom explicit notice, e.g., Read our Explicit Notice regarding CCPA in our %$PPLS$%privacy policy%$PPLE$% page.",
"optOutDetail": "My personalized label for the opt-out button",
"confirm": "My Confirm & Proceed"
}The text between the tags %$PPLS$% and %$PPLE$% is used as the link label to the privacy policy. The underlying link is configured using setPrivacyPolicy.
Just as in GDPR, the publisher may provide all or just some of the labels in the JSON file. However, doing so will lead AdConsent to load the missing labels in the default language, English.
Description
The function can be used to configure different customized text and translations for GDPR and CCPA. Depending on the privacy framework used, the number of supported languages and the level of customization differs. This means there are different sets of translation files for GDPR and CCPA, and setting these translations must be done from within each specific consent law API (e.g., adconsent.gdpr(), adconsent.ccpa()).
Scope
The function must be called before AdConsent shows the GUI. Calls after AdConsent has shown the GUI will be ignored.
Examples
Setting 'en', 'de' and 'pt' custom translations for GDPR coming from 'https://mysite.com/consent/gdpr/translations'
The translation files en.json, de.json and pt.json must be deployed in https://mysite.com/consent/gdpr/translations and be accessible from:
Setting 'de' and 'pt' custom translations for GDPR and 'es' for CCPA
The translation files de.json and pt.json must be deployed in https://mysite.com/consent/gdpr/translations and accessible from:
The translation file es.json must be deployed in https://mysite.com/consent/ccpa/translations and accessible from: