ESCL

EJS String Composition Language (ESCL)

Introduction

The EJS String Composition Language provides a powerful, flexible, and platform agnostic method for composing complex strings and translations. From simple string definitions to complex clauses comprised of custom variables, static terms, compound strings, aliases, functions, embedded links, and custom formatting -- ESCL can handle it all.

ESCL is designed for everyone, including developers, translators, copy writers, etc. This empowers non-developers to work effectively without any programming background.

Concepts

Working with ESCL is a breeze once you understand a few key concepts.

Strings

The most basic element supported by ESCL is a plain string. In this example, the hello_message identifier represents the string Hello, World!.

This string requires no processing or formatting and will be returned verbatim.

Naming Convention

String identifiers must be lower case, alphanumeric, begin with a letter, and may include underscores.

hello_message: 'Hello, World!'

Clauses

A clause in ESCL represents a dynamic part of a string that will be processed. You represent a clause in a string using brace brackets.

my_string: 'This string contains a clause { ... }'

Compound strings

A compound string is a string that is constructed by combining one or more strings. Using a clause, we can pass in the identifier of another string to insert it in place.

Each string is processed independently before being combined.

In this example, tos_message will become Please accept our Terms of Service in English and Veuillez accepter nos conditions d'utilisation in French.

en-US.js

tos_name: 'Terms of Service',
tos_message: 'Please accept our { tos_name }'

fr-CA.js

tos_name: 'conditions d\'utilisation',
tos_message: 'Veuillez accepter nos { tos_name }'

Variables

A variable is a part of a string that will be replaced by values provided by the application. Values may be passed using the $translate instance method or the v-i18n directive.

In this example, the application is expected to provide values for the firstName and lastName variables.

Naming Convention

Variable names must be camel-cased, alphanumeric, and begin with a letter. The colon character (:) indicates the beginning of a variable in the clause definition, but must not be included when passing the argument values.

welcome_message: 'Hello, { :firstName :lastName }, and welcome!'

this.$translate('welcome_message', { firstName: 'John', lastName: 'Doe' });
// Hello, John Doe, and welcome!

<div v-i18n="{ firstName: 'John', lastName: 'Doe' }">welcome_message</div>
<!-- <div>Hello, John Doe, and welcome!</div> -->

Aliases

An alias is a string that contains a single clause which references another string without any additions or modifications.

hello_message: 'Hello, World!',
hi_message: '{ hello_message }'