Development Guides Home >> Guide to Locales

Guide to Locales - Bracket Notation

Introduction

Bracket notation allows you to customize the localized strings in your custom code. This document explains the basic use of of bracket notation in custom applications and interfaces.

  • For additional examples of localization in Template Toolkit files, read our Guide to Template Toolkit in cPanel & WHM documentation.
  • For in-depth documentation about the Locale::Maketext module's methods and additional options, read CPAN's Locale::Maketext::Utils documentation.

Bracket notation basics

The following examples use the asis method to modify the way in which the locale system handles the text bracket notation.

Because the asis method instructs translators not to translate the specified text, these examples would render the following strings after translation:

Language Rendered string
English My text uses bracket notation.
French Mon texte utilise bracket notation.

Perl

Copy
Copied
$locale->maketext('My text uses [asis,bracket notation].');

Template Toolkit

Copy
Copied
[% locale.maketext('My text uses [asis,bracket notation].') %]

JavaScript

Copy
Copied
LOCALE.maketext("My text uses [asis,bracket notation].");

Arguments

The is_defined method will use the following arguments:

  • _1 — The first argument instructs the method to check whether the $value variable is defined.
  • “_1” is an invalid — The second argument provides text that the method will display if the $value variable is defined.
  • Specify a valid — The third argument provides text that the method will display if the $value variable is not defined.

For example, the following examples might render the following strings after translation:

Language Rendered string
English Error: “boop” is an invalid value. Error: Specify a valid value.
French Erreur: "boop" est une valeur non valide. Erreur: Spécifiez une valeur valide.

Many bracket notation methods accept ordered arguments. For example, the following localized strings include three arguments with the is_defined method:

Perl

Copy
Copied
$locale->maketext('Error: [is_defined,_1,"_1" is an invalid,Specify a valid] value.', $value);

Template Toolkit

Copy
Copied
[% locale.maketext('Error: [is_defined,_1,"_1" is an invalid,Specify a valid] value.', $value) %]

JavaScript

Copy
Copied
LOCALE.maketext("Error: [is_defined,_1,"_1" is an invalid,Specify a valid] value.", $value);