<commit_before>===========================
The Guide To The FTL Syntax
===========================

FTL is an open source, localization-specific scripting language used to process 
gender, plurals, conjugations, and most of the other quirky elements of natural 
language.

The following chapters will demonstrate how to use FTL to solve localization 
challenges. Each chapter contains a hands-on example of simple FTL concepts.


Hello World
===========

::

    hello = Hello, World!

This is an entity called ``hello``. Entities are containers for information. 
You use entities to identify, store, and recall information to be used in the 
software's UI.

In its simplest form, an entity stores a value; here it's a string, *Hello, 
World!*. Most of the entities you will work with in FTL will look similar to 
this. Some will be more complex, have more than one value variant, or use 
expressions to select the right variant depending on the circumstances.

How does the information stored in an entity end up on the user's screen and in 
the UI? FTL operates in self-contained instances called "contexts". Each 
context stores information about languages available to it, downloaded resource 
files and all entities in these resource files. Software developers can create 
contexts and query them for values of specific entities.


Working With Text: Multiline, Quote Delimited Strings
=====================================================

::

    about        = About Our Software
    description  =
        | Loki is a simple micro-blogging
        | app written entirely in <i>HTML5</i>.
        | It uses FTL to implement localization.
    more-info     =   "  Read more about us! "

FTL entities mostly store string values. A string is a sequence of characters 
that you can assign to an entity, store, and retrieve.

By default, a string begins after a ``=`` and ends with the end of line.  You 
can also define easy-to-read, multiline strings with a pipe operator, as can be 
seen in the ``description`` entity.

In almost all cases, leading and trailing spaces are not meaningful and will be 
ignored allowing you to align the string id and values in a resource file for 
better readability.  In a rare cases where leading and/or trailing spaces are 
meaningful, FTL allows for special quote delimited strings as can be seen in 
the ``more-info`` entity.


Interpolation and External Arguments
====================================

::

    welcome = Welcome { $user }
    unreadEmails = { $user } has { $emailCount } unread emails.

::

    {
        "user": "Jane",
        "emailCount": 5
    }

In FTL strings may use special syntax to incorporate small pieces of 
programmable interface. Those pieces are denoted with curly braces ``{`` and 
``}`` and are called placeables.  The most common use case for a placeable is 
to put an external argument, provided by the developer, into the string.

There are all kinds of external data that might be useful in providing a good 
localization: user names, number of unread messages, battery level, current 
time, time left before an alarm goes off, etc.

To reference a context data variable, use the dollar syntax in your FTL code: 
``$user``. ``user`` has to be defined in the context data. In the examples 
below, we insert the value of a context data variable into an entity's value.


Builtins
========

::

    emails = You have { $unreadEmails } unread emails.
    emails2 = You have { NUMBER($unreadEmails) } unread emails.

    last-notice =
        | Last checked: { DATETIME($lastChecked, day: "numeric", month: long") }.

::

    {
        "lastChecked": "2016-04-22T08:13:56.354Z",
        "unreadEmails": 5
    }

In some rare cases the data provided by the developer will require some 
additional formatting before it can be placed into the string.  FTL provides 
a list of built-in functions that can help with common operations on the 
external arguments.

By default, FTL can guess which formatter to run on each kind of argument: 
``DATE``, ``NUMBER``, ``LIST`` etc., but you can also call the builtin 
explicitly.

Explicit calls are useful because they allow you to pass 
additional formatting options that may help make the formatted string look 
better in the given language. Examples may be defining month as ``short`` or 
``long`` in the ``DATE`` formatter (using arguments defined in 
``Intl.DateTimeFormat``) or whether to use grouping separator when displaying 
a large number.


Entity References
=================

::

    brandName = Loki
    installing = Installing { brandName }.

    menu-save = Save
    help-menu-save = Click "{ menu-save }" to save the file.

Sometimes it may be useful to reference one entity from another. This generally 
helps to keep certain translations consistent across the interface and makes 
maintenance easier.  It is also particularly handy for keeping branding 
separated from the rest of the translations, so that it can be changed easily 
when needed, e.g. during the build process of the application.

In l20n you can use the same ``{`` and ``}`` syntax to interpolate other 
entities by their identifier.


Selectors
=========<commit_msg>Address feedback for the syntax.rst (#154)<commit_after>===========================
The Guide To The FTL Syntax
===========================

FTL is a localization file format used for describing translation resources.

Software refers to the messages in a given language through unique identifiers.

FTL is designed to be simple to read, but at the same time allows to represent
complex concepts from natural languages like gender, plurals, conjugations,
and others.

The following chapters will demonstrate how to use FTL to solve localization 
challenges. Each chapter contains a hands-on example of simple FTL concepts.


Hello World
===========

::

    hello = Hello, World!

This is an entity called ``hello``. Entities are containers for information. 
You use entities to identify, store, and recall information to be used in the 
software's UI.

In its simplest form, an entity has just a single string value; here *Hello,
World!*. Most of the entities you will work with in FTL will look similar to 
this. Some will be more complex, have more than one value variant, or use 
expressions to select the right variant depending on the circumstances.


Working With Text: Multiline, Quote Delimited Strings
=====================================================

::

    about        = About Our Software
    description  =
        | Loki is a simple micro-blogging
        | app written entirely in <i>HTML5</i>.
        | It uses FTL to implement localization.
    more-info     =   "  Read more about us! "

The value of an FTL entity is usually a simple string.

By default, a string begins after a ``=`` and ends with the end of line.  You 
can also define easy-to-read, multiline strings with a pipe mark-up, as can be
seen in the ``description`` entity.

FTL ignores leading whitespaces in front of the value allowing localizers to
align their messages for readability.
For multiline strings, whitespaces both before and after the pipe are ignored.
In rare cases where leading whitespaces should be part of the value, FTL allows
for special quote delimited strings as can be seen in
the ``more-info`` entity.


Entity References
=================

::

    brandName = Loki
    installing = Installing { brandName }.

    menu-save = Save
    help-menu-save = Click "{ menu-save }" to save the file.

Strings in FTL may use special syntax to incorporate small pieces of
programmable interface. Those pieces are denoted with curly braces ``{`` and
``}`` and are called placeables.

One example of a placeable is a reference to another entity.

Referencing other entities generally helps to keep certain translations
consistent across the interface and makes maintenance easier.  It is also
particularly handy for keeping branding separated from the rest of the
translations, so that it can be changed easily when needed, e.g. during the
build process of the application.


Interpolation and External Arguments
====================================

::

    welcome = Welcome { $user }
    unreadEmails = { $user } has { $emailCount } unread emails.

::

    {
        "user": "Jane",
        "emailCount": 5
    }


Another common common use case for a placeable is to put an external argument,
provided by the developer, into the string.

There are all kinds of external data that might be useful in providing a good 
localization: user names, number of unread messages, battery level, current 
time, time left before an alarm goes off, etc.

To reference a context data variable, use the dollar syntax in your FTL code: 
``$user``. ``user`` has to be defined in the context data. In the examples 
below, we insert the value of a context data variable into an entity's value.


Builtins
========

::

    emails = You have { $unreadEmails } unread emails.
    emails2 = You have { NUMBER($unreadEmails) } unread emails.

    last-notice =
        | Last checked: { DATETIME($lastChecked, day: "numeric", month: long") }.

::

    {
        "lastChecked": "2016-04-22T08:13:56.354Z",
        "unreadEmails": 5
    }

In some rare cases the data provided by the developer will require some 
additional formatting before it can be placed into the string.  FTL provides 
a list of built-in functions that can help with common operations on the 
external arguments.

By default, FTL can guess which formatter to run on each kind of argument: 
``DATE``, ``NUMBER``, ``LIST`` etc., but you can also call the builtin 
explicitly.

Explicit calls are useful because they allow you to pass 
additional formatting options that may help make the formatted string look 
better in the given language. Examples may be defining month as ``short`` or 
``long`` in the ``DATE`` formatter (using arguments defined in 
``Intl.DateTimeFormat``) or whether to use grouping separator when displaying 
a large number.


Selectors
=========
{'fraction_non_alphanumeric': 0.0945472736368184, 'fraction_numerical': 0.004702351175587794, 'mean_word_length': 3.812710640346654, 'pattern_counts': {'":': 8, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 1, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7437541', 'n_tokens_mistral': 2665, 'n_tokens_neox': 2499, 'n_words': 1383}