sre-l10n

Localisations for SRE

View on GitHub

Localisation of SRE

Localisation of SRE consists effectively of four separate steps:

Below is a an explanation of the actual speech rule sets that need localising as well as a description of the Yaml format of SRE speech rules.

Speech Rule Sets

SRE gnerally uses four rule sets for translation of mathematical expressions into speech. Note, that there exist a couple of extra rule sets for English, which are generally not localised.

MathSpeak

This is a fairly simple rule set that aims at speaking mathematical expressions in relatively straight forward fashion adding disambiguating language in order to indicate two dimensional layout and nested terms or formulas. It offers three reading styles: vebose, brief and superbrief.

As an example, consider the nested fraction

 \frac{a}{\frac{b}{c}}

is translated in verbose style to

StartStartFraction a OverOver StartFraction b Over c EndFraction EndEndFraction

and in super brief style to

NestFrac a NestOver Frac b Over c EndFrac NestEndFrac

Localisation of MathSpeak consists of the translation of a relatively small number of speech rules together with the translation of a set of messages that are used to construct disambiguating terms, e.g., Start, Fraction, End etc.

ClearSpeak

This is a more natural speaking style, which in addition offers a considerable number of speech preferences that allow fine tuning of how expressions are spoken. Clearspeak works a lot with pausing to achieve disambiguation. As a consequence it has considerably more rules that need translation.

E.g., the above fraction would be spoken in standard Clearspeak as

the fraction with numerator a and denominator b over c

or in Fraction preference FracOver as

the fraction a over the fraction b over c

Note, that Clearspeak uses a notion of simple terms expressions to simplify speech when possible. In the above example b and c are considered simple terms, leading to a shortened transcription of the fraction, while b over c is considered a complex term so the overall fraction is spoken in more detail.

Another example is juxtaposition where xy is simple versus other infix operators like x + y, which is not simple.

Prefix

Prefixes are used in order to indicate positions of terms. They are important to provide context for a particular term when exploring an expression in more detail. For example in the fraction \frac{a}{b} the term a would get the prefix Numerator while b would get Denominator. Prefix rules are very simple, generally only consisting of single terms that need translating.

Summary

Summary rules allow for summarising terms by their primary component. For example an addition of the form a + b + c would be summarised as sum with three summands regardless of the complexity of a, b, or c. While there are considerably more summary rules than prefix rules, they are still relatively simple to translate.

Yaml format

Speech rule sets are given in a Yaml format, where each speech rule is presented as follows:

# Comment consisting of the rule description
# Example: An optional example
# LaTeX Example: An optional latex code example
# Parameter descriptions: One per rule parameter of the form %i.
# %1: 
# ...
# %n:
rulename:
    - %i (optional annotation)
    - $j: "message" (optional annotation)
    ...

Here %i and $j are parameter indicators, which are explained in more detail below. For now it is important to note that parameters of type $ need to be translated, while those of type % do not.

As an example consider the following speech rule for absolute value:

# The fraction rule in auto mode.
# %1: The numerator
# %2: The denominator
fraction:
  - $1: "the" (grammar:article)
  - $2: "fraction with numerator"
  - %1 (pause:short)
  - $3: "and denominator"
  - %2 (pause:short)

The rule has two parameters representing the numerator and denominator. It consists of five lines: three string messages $1, $2, $3 and the two parameters %1, %2. These are assembled in sequence, once terms plugged into the parameters %1, %2 are evaluated. For example the expression \frac{a+b}{c} is pronounced as

the fraction with numerator a plus b and denominator c

after the expression a+b is evaluated to a plus b.

Note, that lines can be deleted or rearranged. For the sake of the example assume we want to speak denominator before numerator and omit the article. This could be achieved by changing the rule as follows:

# The fraction rule in auto mode.
# %1: The numerator
# %2: The denominator
fraction:
  - $2: "fraction with denominator"
  - %2 (pause:short)
  - $3: "and numerator"
  - %1 (pause:short)

This would now lead to the speech output of

fraction with denominator c and enumerator a plus b

Note that some of the lines contain annotations. While they are desribed in more detail below, for now it is sufficient to understand that pauses can be added in any line (provided you think they are useful).

Grammar annotations are more subtle, in that they convey and propagate meaning. E.g., the article annotation ensures that articles are not repeated in English. In other locales this annotation can be used to adapt the case of the article.

Localising a Speech Rule

Localisation generally consists of three parts:

  1. translating the string messages
  2. arranging or rearranging the order in which speech is assembled
  3. localising or adapting annotations

As example for 1. consider the localisation of the clearspeak rule for fractions into French:

fraction:
  - $1: "fraction avec numérateur"
  - %1 (pause:short)
  - $2: "et dénominateur"
  - %2 (pause:short)

As an example for 2. consider the rule for adding explicit font information:

# Explicit speaking of font
# Example: bold alpha
# %1: The font
# %2: The expression
font:
  - %1
  - %2 (pause:short)

Note that there is nothing to translate, however, localisation consists of potentially altering the order of the parameters. For instance the French version of the rule looks as follows:

# Explicit speaking of font
# Example: alpha en gras
# %1: The font
# %2: The expression
font:
  - %2
  - %1 (pause:short)

For the final category of adapting and localising annotations see the section on annotations below.

Parameter indicators

We use two types of parameter indicators %n and $n, both at the start of component lines.

%n: These refer to parameters that are recursively translated and are explained in the comments. Please do not change the parameter.

$n: These are reference parameters for textual elements that need to be localised. Please leave the $n mark as is in the front of the line. You can nevertheless rearrange, or delete the line. Likewise you can add new lines with textual content given in double quotes. There is no need to give a newly added line a reference parameter.

Annotations

Localisable Annotations

There exist three types of annotations that can contain localisable strings.

The first two annotations will only ever occur on % parameters, which represent multiple elements that are translated as a list. The join annotation can occur for any parameter.

Separator Example:
# Subtraction
# Example: a minus b minus c
# LaTeX Example: $a - b - c$
# %1: List of components of the subtraction
subtraction:
  - %1 (separator:"minus")
Context Example:
# Iterates over a matrix row.
# %1: The list of single cells in the row.
matrix-row:
  - %1 (context:"Column-,- ", pause:long)

Note that context elements can contain control characters (-,- in the above example) that are best left alone!

Pauses

Pauses can be added to both types of parameters in the form of (pause:short) for instance. Pauses generally can have numerical values in milliseconds or relative pauses in terms of short, medium, long. Pauses are accumulative and the given value is the minimal pause that will be used. That is, even if a pause is defined as small, it can be longer in case the preceding expression requires this. In case it is defined as medium or long than the pause will be at least medium or long no matter how small the preceding expression is.

Grammar

Grammar annotations can also be added on both types of parameters. When added to $ string messages they generally lead to some kind of post-processing (e.g., putting an article into the right grammatical case). When used on a % parameter, they propagate some information that can be used when translating the expression the parameter represents.

The following is a list of commonly used grammar annotations:

Annotation Value Meaning
singular None The expression is in singular. Used, e.g., for units or vulgar fractions
plural None The expression is in plural. Used, e.g., for units or vulgar fractions
dual None The expression is in dual. Used, e.g., for units or vulgar fractions
     
case nominative, dative, … Grammatical case for the expressionn
gender m, f, n Grammatical gender of the expression
     
article None Marks an article. Used for post-processing by removing duplicates or putting the article into the correct gender or case.
     

It can be necessary to remove grammatical annotations, for example when a case is no longer valid. This can be achieved by adding an exclamation mark before the annotation, or in other words, negating it. E.g., (grammar:!singular) removes the grammatical annotation singular.

Note, adding grammar categories often requires some adjustment of preconditions for rules. These have to be done explicitly in the rule sets, and can not be done via the yaml files. For more information, best to contact the owner of this repository directly.