Skip to contents

Source Text and Translations

Source: R/class-translator.R
class-translator.Rd

Structure and manipulate the source text of a project and its translations.

Usage

translator(..., id = uuid(), algorithm = algorithms())

is_translator(x)

# S3 method for class 'Translator'
format(x, ...)

# S3 method for class 'Translator'
print(x, ...)

Arguments

...

Usage depends on the underlying function.

  • Any number of Text objects and/or named character strings for translator() (in no preferred order).

  • Further arguments passed to or from other methods for format(), and print().

id

A non-empty and non-NA character string. A globally unique identifier for the Translator object. Beware of collisions when using user-defined values.

algorithm

A non-empty and non-NA character string equal to "sha1", or "utf8". The algorithm to use when hashing source information for identification purposes.

x

Any R object.

Value

translator() returns an R6 object of class Translator.

is_translator() returns a logical value.

format() returns a character vector.

print() returns argument x invisibly.

Details

A Translator object encapsulates the source text of a project (or any other context) and all related translations. Under the hood, Translator objects are collections of Text objects. These do most of the work. They are treated as lower-level component and in typical situations, users rarely interact with them.

Translator objects can be saved and exported with translator_write(). They can be imported back into an R session with translator_read().

See also

find_source(), translator_read(), translator_write()

Active bindings

id

A non-empty and non-NA character string. A globally unique identifier for the underlying object. Beware of plausible collisions when using user-defined values.

algorithm

A non-empty and non-NA character string equal to "sha1", or "utf8". The algorithm to use when hashing source information for identification purposes.

hashes

A character vector of non-empty and non-NA values, or NULL. The set of all hash exposed by registered Text objects. If there is none, hashes is NULL. This is a read-only field updated whenever field algorithm is updated.

source_texts

A character vector of non-empty and non-NA values, or NULL. The set of all registered source texts. If there is none, source_texts is NULL. This is a read-only field.

source_langs

A character vector of non-empty and non-NA values, or NULL. The set of all registered source languages. This is a read-only field.

  • If there is none, source_langs is NULL.

  • If there is one unique value, source_langs is an unnamed character string.

  • Otherwise, it is a named character vector.

languages

A character vector of non-empty and non-NA values, or NULL. The set of all registered languages (codes). If there is none, languages is NULL. This is a read-only field.

native_languages

A named character vector of non-empty and non-NA values, or NULL. A map (bijection) of languages (codes) to native language names. Names are codes and values are native languages. If there is none, native_languages is NULL.

While users retain full control over native_languages, it is best to use well-known schemes such as IETF BCP 47, or ISO 639-1. Doing so maximizes portability and cross-compatibility between packages.

Update this field with method $set_native_languages(). See below for more information.

Methods

Public methods

Method new()

Create a Translator object.

Usage

Translator$new(id = uuid(), algorithm = algorithms())

Arguments

id

A non-empty and non-NA character string. A globally unique identifier for the Translator object. Beware of collisions when using user-defined values.

algorithm

A non-empty and non-NA character string equal to "sha1", or "utf8". The algorithm to use when hashing source information for identification purposes.

Returns

An R6 object of class Translator.

Examples

# Consider using translator() instead.
tr <- Translator$new()

Method translate()

Translate source text.

Usage

Translator$translate(
  ...,
  lang = language_get(),
  source_lang = language_source_get()
)

Arguments

...

Any number of vectors containing atomic elements. Each vector is normalized as a paragraph.

  • Elements are coerced to character values.

  • NA values and empty strings are discarded.

  • Multi-line strings are supported and encouraged. Blank lines are interpreted (two or more newline characters) as paragraph separators.

lang

A non-empty and non-NA character string. The underlying language.

A language is usually a code (of two or three letters) for a native language name. While users retain full control over codes, it is best to use language codes stemming from well-known schemes such as IETF BCP 47, or ISO 639-1 to maximize portability and cross-compatibility.

source_lang

A non-empty and non-NA character string. The language of the source text. See argument lang for more information.

Details

See normalize() for further details on how ... is normalized.

Returns

A character string. If there is no corresponding translation, the value passed to method $set_default_value() is returned. NULL is returned by default.

Examples

tr <- Translator$new()
tr$set_text(en = "Hello, world!", fr = "Bonjour, monde!")
tr$translate("Hello, world!", lang = "en")  ## Outputs "Hello, world!"
tr$translate("Hello, world!", lang = "fr")  ## Outputs "Bonjour, monde!"

Method get_translation()

Extract a translation or a source text.

Usage

Translator$get_translation(hash = "", lang = "")

Arguments

hash

A non-empty and non-NA character string. The unique identifier of the requested source text.

lang

A non-empty and non-NA character string. The underlying language.

A language is usually a code (of two or three letters) for a native language name. While users retain full control over codes, it is best to use language codes stemming from well-known schemes such as IETF BCP 47, or ISO 639-1 to maximize portability and cross-compatibility.

Returns

A character string. If there is no corresponding translation, the value passed to method $set_default_value() is returned. NULL is returned by default.

Examples

tr <- Translator$new()
tr$set_text(en = "Hello, world!")

# Consider using translate() instead.
tr$get_translation("256e0d7", "en")  ## Outputs "Hello, world!"

Method get_text()

Extract a source text and its translations.

Usage

Translator$get_text(hash = "")

Arguments

hash

A non-empty and non-NA character string. The unique identifier of the requested source text.

Returns

A Text object, or NULL.

Examples

tr <- Translator$new()
tr$set_text(en = "Hello, world!")

tr$get_translation("256e0d7", "en")  ## Outputs "Hello, world!"

Method set_text()

Register a source text.

Usage

Translator$set_text(..., source_lang = language_source_get())

Arguments

...

Passed as is to text().

source_lang

Passed as is to text().

Returns

A NULL, invisibly.

Examples

tr <- Translator$new()

tr$set_text(en = "Hello, world!", location())

Method set_texts()

Register one or more source texts.

Usage

Translator$set_texts(...)

Arguments

...

Any number of Text objects.

Details

This method calls merge_texts() to merge all values passed to ... together with previously registered Text objects. The underlying registered source texts, translations, and Location objects won't be duplicated.

Returns

A NULL, invisibly.

Examples

# Set source language.
language_source_set("en")

tr <- Translator$new()

# Create Text objects.
txt1 <- text(
  location("a", 1L, 2L, 3L, 4L),
  en = "Hello, world!",
  fr = "Bonjour, monde!")

txt2 <- text(
  location("b", 5L, 6L, 7L, 8L),
  en = "Farewell, world!",
  fr = "Au revoir, monde!")

tr$set_texts(txt1, txt2)

Method rm_text()

Remove a registered source text.

Usage

Translator$rm_text(hash = "")

Arguments

hash

A non-empty and non-NA character string identifying the source text to remove.

Returns

A NULL, invisibly.

Examples

tr <- Translator$new()
tr$set_text(en = "Hello, world!")

tr$rm_text("256e0d7")

Method set_native_languages()

Map a language code to a native language name.

Usage

Translator$set_native_languages(...)

Arguments

...

Any number of named, non-empty, and non-NA character strings. Names are codes and values are native languages. See field native_languages for more information.

Returns

A NULL, invisibly.

Examples

tr <- Translator$new()

tr$set_native_languages(en = "English", fr = "Français")

# Remove existing entries.
tr$set_native_languages(fr = NULL)

Method set_default_value()

Register a default value to return when there is no corresponding translations for the requested language.

Usage

Translator$set_default_value(value = NULL)

Arguments

value

A NULL or a non-NA character string. It can be empty. The former is returned by default.

Details

This modifies what methods $translate() and $get_translation() returns when there is no translation for lang.

Returns

A NULL, invisibly.

Examples

tr <- Translator$new()
tr$set_default_value("<unavailable>")

Examples

# Set source language.
language_source_set("en")

# Create a Translator object.
# This would normally be done automatically
# by find_source(), or translator_read().
tr <- translator(
  id = "test-translator",
  en = "English",
  es = "Español",
  fr = "Français",
  text(
    location("a", 1L, 2L, 3L, 4L),
    en = "Hello, world!",
    fr = "Bonjour, monde!"),
  text(
    location("b", 1L, 2L, 3L, 4L),
    en = "Farewell, world!",
    fr = "Au revoir, monde!"))

is_translator(tr)

# Translator objects has a specific format.
# print() calls format() internally, as expected.
print(tr)


## ------------------------------------------------
## Method `Translator$new`
## ------------------------------------------------

# Consider using translator() instead.
tr <- Translator$new()

## ------------------------------------------------
## Method `Translator$translate`
## ------------------------------------------------

tr <- Translator$new()
tr$set_text(en = "Hello, world!", fr = "Bonjour, monde!")
tr$translate("Hello, world!", lang = "en")  ## Outputs "Hello, world!"
tr$translate("Hello, world!", lang = "fr")  ## Outputs "Bonjour, monde!"

## ------------------------------------------------
## Method `Translator$get_translation`
## ------------------------------------------------

tr <- Translator$new()
tr$set_text(en = "Hello, world!")

# Consider using translate() instead.
tr$get_translation("256e0d7", "en")  ## Outputs "Hello, world!"

## ------------------------------------------------
## Method `Translator$get_text`
## ------------------------------------------------

tr <- Translator$new()
tr$set_text(en = "Hello, world!")

tr$get_translation("256e0d7", "en")  ## Outputs "Hello, world!"

## ------------------------------------------------
## Method `Translator$set_text`
## ------------------------------------------------

tr <- Translator$new()

tr$set_text(en = "Hello, world!", location())

## ------------------------------------------------
## Method `Translator$set_texts`
## ------------------------------------------------

# Set source language.
language_source_set("en")

tr <- Translator$new()

# Create Text objects.
txt1 <- text(
  location("a", 1L, 2L, 3L, 4L),
  en = "Hello, world!",
  fr = "Bonjour, monde!")

txt2 <- text(
  location("b", 5L, 6L, 7L, 8L),
  en = "Farewell, world!",
  fr = "Au revoir, monde!")

tr$set_texts(txt1, txt2)

## ------------------------------------------------
## Method `Translator$rm_text`
## ------------------------------------------------

tr <- Translator$new()
tr$set_text(en = "Hello, world!")

tr$rm_text("256e0d7")

## ------------------------------------------------
## Method `Translator$set_native_languages`
## ------------------------------------------------

tr <- Translator$new()

tr$set_native_languages(en = "English", fr = "Français")

# Remove existing entries.
tr$set_native_languages(fr = NULL)

## ------------------------------------------------
## Method `Translator$set_default_value`
## ------------------------------------------------

tr <- Translator$new()
tr$set_default_value("<unavailable>")