class-text: Source Text
In transltr: Support Many Languages in R
text R Documentation
Source Text
Description
Structure source text and its translations.
Usage
text(..., source_lang = language_source_get(), algorithm = algorithms())
is_text(x)
## S3 method for class 'Text'
format(x, ...)
## S3 method for class 'Text'
print(x, ...)
## S3 method for class 'Text'
c(...)
merge_texts(..., algorithm = algorithms())
as_text(x, ...)
## S3 method for class 'call'
as_text(x, loc = location(), algorithm = algorithms(), ...)
Arguments
...
Usage depends on the underlying function.
Any number of Location objects and/or named character
strings for text() (in no preferred order).
Any number of Text objects for merge_texts() and S3
method c().
Further arguments passed to or from other methods for format(),
print(), and as_text().
source_lang
A non-empty and non-NA character string. The language of
the source text.
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.
Doing so maximizes portability and cross-compatibility between packages.
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.
loc
A Location object.
Details
A Text object is a piece of source text that is extracted from R
source scripts.
It (typically) has one or more Locations within a project.
It has zero or more translations.
The Text class structures this information and exposes a set of
methods to manipulate it.
Combining Text Objects
c() can only combine Text objects having the same hash.
This is equivalent to having the same algorithm, source_lang, and
source_text. In that case, the underlying translations and
Location objects are combined and a new object is returned.
It throws an error if all Text objects are empty (they have no
set source_lang).
merge_texts() is a generalized version of c() that handles any number
of Text objects having possibly different hashes. It can be
viewed as a vectorized version of c(). It silently ignores and drops
all empty Text objects.
Coercion
as_text() is an S3 generic function that attempts to coerce its argument
into a suitable Text object. as_text.call() is the method used
by find_source() to coerce a call object to a Text
object. While it can be used, it should be avoided most of the time. Users
may extend it by defining their own methods.
Value
text(), c(), and as_text() return an R6 object of
class Text.
is_text() returns a logical value.
format() returns a character vector.
print() returns argument x invisibly.
merge_texts() returns a list of (combined) Text objects. It
can be empty if all underlying Text objects are empty.
Active bindings
hashA non-empty and non-NA character string. A reproducible
hash generated from source_lang and source_text, and by using
the algorithm specified by algorithm. It is used as a unique
identifier for the underlying Text object.
This is a read-only field. It is automatically updated
whenever fields source_lang and/or algorithm are updated.
algorithmA non-empty and non-NA character string equal to "sha1",
or "utf8". The algorithm to use when hashing source information for
identification purposes.
source_langA non-empty and non-NA character string. The language of
the source text.
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.
Doing so maximizes portability and cross-compatibility between packages.
source_textA non-empty and non-NA character string. The source text.
This is a read-only field.
languagesA character vector. Registered language
codes. This is a read-only field. Use methods below
to update it.
translationsA named character vector. Registered
translations of source_text, including the latter. Names
correspond to languages. This is a read-only field.
Use methods below to update it.
locationsA list of Location objects giving
the location(s) of source_text in the underlying project. It
can be empty. This is a read-only field. Use methods below
to update it.
Methods
Public methods
-
-
-
-
-
-
-
Method new()
Create a Text object.
Usage
Text$new(algorithm = algorithms())
Arguments
algorithmA 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 Text.
Examples
# Consider using text() instead.
txt <- Text$new()
Method get_translation()
Extract a translation, or the source text.
Usage
Text$get_translation(lang = "")
Arguments
langA 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. NULL is returned if the requested
translation is not available.
Examples
txt <- Text$new()
txt$set_translation("en", "Hello, world!")
txt$get_translation("en") ## Outputs "Hello, world!"
txt$get_translation("fr") ## Outputs NULL
Method set_translation()
Register a translation, or the source text.
Usage
Text$set_translation(lang = "", text = "")
Arguments
langA 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.
textA non-empty and non-NA character string. A translation,
or the source text.
Details
This method is also used to register source_lang and
source_text before setting them as such. See Examples below.
Returns
A NULL, invisibly.
Examples
# Register a pair of source_lang and source_text.
txt <- Text$new()
txt$set_translation("en", "Hello, world!")
txt$source_lang <- "en"
Method set_translations()
Register one or more translations, and/or the source
text.
Usage
Text$set_translations(...)
Arguments
...Any number of named, non-empty, and non-NA character
strings.
Details
This method can be viewed as a vectorized version of
method set_translation().
Returns
A NULL, invisibly.
Examples
txt <- Text$new()
txt$set_translations(en = "Hello, world!", fr = "Bonjour, monde!")
Method set_locations()
Register one or more locations.
Usage
Text$set_locations(...)
Arguments
...Any number of Location objects.
Details
This method calls merge_locations() to merge all
values passed to ... together with previously registered
Location objects. The underlying registered
paths and/or ranges won't be duplicated.
Returns
A NULL, invisibly.
Examples
txt <- Text$new()
txt$set_locations(
location("a", 1L, 2L, 3L, 4L),
location("a", 1L, 2L, 3L, 4L),
location("b", 5L, 6L, 7L, 8L))
Method rm_translation()
Remove a registered translation.
Usage
Text$rm_translation(lang = "")
Arguments
langA non-empty and non-NA character string identifying a
translation to be removed.
Details
You cannot remove lang when it is registered as the
current source_lang. You must update source_lang before
doing so.
Returns
A NULL, invisibly.
Examples
txt <- Text$new()
txt$set_translations(en = "Hello, world!", fr = "Bonjour, monde!")
txt$source_lang <- "en"
# Remove source_lang and source_text.
txt$source_lang <- "fr"
txt$rm_translation("en")
Method rm_location()
Remove a registered location.
Usage
Text$rm_location(path = "")
Arguments
pathA non-empty and non-NA character string identifying a
Location object to be removed.
Returns
A NULL, invisibly.
Examples
txt <- Text$new()
txt$set_locations(
location("a", 1L, 2L, 3L, 4L),
location("b", 5L, 6L, 7L, 8L))
txt$rm_location("a")
Examples
# Set source language.
language_source_set("en")
# Create Text objects.
txt1 <- text(
location("a", 1L, 2L, 3L, 4L),
location("a", 1L, 2L, 3L, 4L),
location("b", 5L, 6L, 7L, 8L),
location("c", c(9L, 10L), c(11L, 12L), c(13L, 14L), c(15L, 16L)),
en = "Hello, world!",
fr = "Bonjour, monde!",
es = "¡Hola, mundo!")
txt2 <- text(
location("a", 1L, 2L, 3L, 4L),
en = "Hello, world!",
fr = "Bonjour, monde!",
es = "¡Hola, mundo!")
txt3 <- text(
source_lang = "fr2",
location("a", 5L, 6L, 7L, 8L),
en = "Hello, world!",
fr2 = "Bonjour le monde!",
es = "¡Hola, mundo!")
is_text(txt1)
# Texts objects has a specific format.
# print() calls format() internally, as expected.
print(txt1)
print(txt2)
print(txt3)
# Combine Texts objects.
# c() throws an error if they do not have the same
# hash (same souce_text, source_lang, and algorithm).
c(txt1, txt2)
# Text objects with different hashes can be merged.
# This groups Text objects according to their hashes
# and calls c() on each group. It returns a list.
merge_texts(txt1, txt2, txt3)
# Objects can be coerced to a Text object with as_text(). Below is an
# example for call objects. This is for illustration purposes only,
# and the latter should not be used. This method is used internally by
# find_source().
cl <- str2lang("translate('Hello, world!')")
loc <- location("example in class-text", 2L, 32L, 2L, 68L)
as_text(cl, loc)
## ------------------------------------------------
## Method `Text$new`
## ------------------------------------------------
# Consider using text() instead.
txt <- Text$new()
## ------------------------------------------------
## Method `Text$get_translation`
## ------------------------------------------------
txt <- Text$new()
txt$set_translation("en", "Hello, world!")
txt$get_translation("en") ## Outputs "Hello, world!"
txt$get_translation("fr") ## Outputs NULL
## ------------------------------------------------
## Method `Text$set_translation`
## ------------------------------------------------
# Register a pair of source_lang and source_text.
txt <- Text$new()
txt$set_translation("en", "Hello, world!")
txt$source_lang <- "en"
## ------------------------------------------------
## Method `Text$set_translations`
## ------------------------------------------------
txt <- Text$new()
txt$set_translations(en = "Hello, world!", fr = "Bonjour, monde!")
## ------------------------------------------------
## Method `Text$set_locations`
## ------------------------------------------------
txt <- Text$new()
txt$set_locations(
location("a", 1L, 2L, 3L, 4L),
location("a", 1L, 2L, 3L, 4L),
location("b", 5L, 6L, 7L, 8L))
## ------------------------------------------------
## Method `Text$rm_translation`
## ------------------------------------------------
txt <- Text$new()
txt$set_translations(en = "Hello, world!", fr = "Bonjour, monde!")
txt$source_lang <- "en"
# Remove source_lang and source_text.
txt$source_lang <- "fr"
txt$rm_translation("en")
## ------------------------------------------------
## Method `Text$rm_location`
## ------------------------------------------------
txt <- Text$new()
txt$set_locations(
location("a", 1L, 2L, 3L, 4L),
location("b", 5L, 6L, 7L, 8L))
txt$rm_location("a")
transltr documentation built on April 3, 2025, 9:33 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| text | R Documentation |
Source Text
Description
Structure source text and its translations.
Usage
text(..., source_lang = language_source_get(), algorithm = algorithms())
is_text(x)
## S3 method for class 'Text'
format(x, ...)
## S3 method for class 'Text'
print(x, ...)
## S3 method for class 'Text'
c(...)
merge_texts(..., algorithm = algorithms())
as_text(x, ...)
## S3 method for class 'call'
as_text(x, loc = location(), algorithm = algorithms(), ...)
Arguments
... |
Usage depends on the underlying function.
|
source_lang |
A non-empty and non-NA character string. The language of the source text. 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. Doing so maximizes portability and cross-compatibility between packages. |
algorithm |
A non-empty and non-NA character string equal to |
x |
Any R object. |
loc |
A |
Details
A Text object is a piece of source text that is extracted from R
source scripts.
It (typically) has one or more
Locationswithin a project.It has zero or more translations.
The Text class structures this information and exposes a set of
methods to manipulate it.
Combining Text Objects
c() can only combine Text objects having the same hash.
This is equivalent to having the same algorithm, source_lang, and
source_text. In that case, the underlying translations and
Location objects are combined and a new object is returned.
It throws an error if all Text objects are empty (they have no
set source_lang).
merge_texts() is a generalized version of c() that handles any number
of Text objects having possibly different hashes. It can be
viewed as a vectorized version of c(). It silently ignores and drops
all empty Text objects.
Coercion
as_text() is an S3 generic function that attempts to coerce its argument
into a suitable Text object. as_text.call() is the method used
by find_source() to coerce a call object to a Text
object. While it can be used, it should be avoided most of the time. Users
may extend it by defining their own methods.
Value
text(), c(), and as_text() return an R6 object of
class Text.
is_text() returns a logical value.
format() returns a character vector.
print() returns argument x invisibly.
merge_texts() returns a list of (combined) Text objects. It
can be empty if all underlying Text objects are empty.
Active bindings
hashA non-empty and non-NA character string. A reproducible hash generated from
source_langandsource_text, and by using the algorithm specified byalgorithm. It is used as a unique identifier for the underlyingTextobject.This is a read-only field. It is automatically updated whenever fields
source_langand/oralgorithmare updated.algorithmA non-empty and non-NA character string equal to
"sha1", or"utf8". The algorithm to use when hashing source information for identification purposes.source_langA non-empty and non-NA character string. The language of the source text.
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. Doing so maximizes portability and cross-compatibility between packages.
source_textA non-empty and non-NA character string. The source text. This is a read-only field.
languagesA character vector. Registered language codes. This is a read-only field. Use methods below to update it.
translationsA named character vector. Registered translations of
source_text, including the latter. Names correspond tolanguages. This is a read-only field. Use methods below to update it.locationsA list of
Locationobjects giving the location(s) ofsource_textin the underlying project. It can be empty. This is a read-only field. Use methods below to update it.
Methods
Public methods
Method new()
Create a Text object.
Usage
Text$new(algorithm = algorithms())
Arguments
algorithmA 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 Text.
Examples
# Consider using text() instead. txt <- Text$new()
Method get_translation()
Extract a translation, or the source text.
Usage
Text$get_translation(lang = "")
Arguments
langA 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. NULL is returned if the requested
translation is not available.
Examples
txt <- Text$new()
txt$set_translation("en", "Hello, world!")
txt$get_translation("en") ## Outputs "Hello, world!"
txt$get_translation("fr") ## Outputs NULL
Method set_translation()
Register a translation, or the source text.
Usage
Text$set_translation(lang = "", text = "")
Arguments
langA 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.
textA non-empty and non-NA character string. A translation, or the source text.
Details
This method is also used to register source_lang and
source_text before setting them as such. See Examples below.
Returns
A NULL, invisibly.
Examples
# Register a pair of source_lang and source_text.
txt <- Text$new()
txt$set_translation("en", "Hello, world!")
txt$source_lang <- "en"
Method set_translations()
Register one or more translations, and/or the source text.
Usage
Text$set_translations(...)
Arguments
...Any number of named, non-empty, and non-NA character strings.
Details
This method can be viewed as a vectorized version of
method set_translation().
Returns
A NULL, invisibly.
Examples
txt <- Text$new() txt$set_translations(en = "Hello, world!", fr = "Bonjour, monde!")
Method set_locations()
Register one or more locations.
Usage
Text$set_locations(...)
Arguments
...Any number of
Locationobjects.
Details
This method calls merge_locations() to merge all
values passed to ... together with previously registered
Location objects. The underlying registered
paths and/or ranges won't be duplicated.
Returns
A NULL, invisibly.
Examples
txt <- Text$new()
txt$set_locations(
location("a", 1L, 2L, 3L, 4L),
location("a", 1L, 2L, 3L, 4L),
location("b", 5L, 6L, 7L, 8L))
Method rm_translation()
Remove a registered translation.
Usage
Text$rm_translation(lang = "")
Arguments
langA non-empty and non-NA character string identifying a translation to be removed.
Details
You cannot remove lang when it is registered as the
current source_lang. You must update source_lang before
doing so.
Returns
A NULL, invisibly.
Examples
txt <- Text$new()
txt$set_translations(en = "Hello, world!", fr = "Bonjour, monde!")
txt$source_lang <- "en"
# Remove source_lang and source_text.
txt$source_lang <- "fr"
txt$rm_translation("en")
Method rm_location()
Remove a registered location.
Usage
Text$rm_location(path = "")
Arguments
pathA non-empty and non-NA character string identifying a
Locationobject to be removed.
Returns
A NULL, invisibly.
Examples
txt <- Text$new()
txt$set_locations(
location("a", 1L, 2L, 3L, 4L),
location("b", 5L, 6L, 7L, 8L))
txt$rm_location("a")
Examples
# Set source language.
language_source_set("en")
# Create Text objects.
txt1 <- text(
location("a", 1L, 2L, 3L, 4L),
location("a", 1L, 2L, 3L, 4L),
location("b", 5L, 6L, 7L, 8L),
location("c", c(9L, 10L), c(11L, 12L), c(13L, 14L), c(15L, 16L)),
en = "Hello, world!",
fr = "Bonjour, monde!",
es = "¡Hola, mundo!")
txt2 <- text(
location("a", 1L, 2L, 3L, 4L),
en = "Hello, world!",
fr = "Bonjour, monde!",
es = "¡Hola, mundo!")
txt3 <- text(
source_lang = "fr2",
location("a", 5L, 6L, 7L, 8L),
en = "Hello, world!",
fr2 = "Bonjour le monde!",
es = "¡Hola, mundo!")
is_text(txt1)
# Texts objects has a specific format.
# print() calls format() internally, as expected.
print(txt1)
print(txt2)
print(txt3)
# Combine Texts objects.
# c() throws an error if they do not have the same
# hash (same souce_text, source_lang, and algorithm).
c(txt1, txt2)
# Text objects with different hashes can be merged.
# This groups Text objects according to their hashes
# and calls c() on each group. It returns a list.
merge_texts(txt1, txt2, txt3)
# Objects can be coerced to a Text object with as_text(). Below is an
# example for call objects. This is for illustration purposes only,
# and the latter should not be used. This method is used internally by
# find_source().
cl <- str2lang("translate('Hello, world!')")
loc <- location("example in class-text", 2L, 32L, 2L, 68L)
as_text(cl, loc)
## ------------------------------------------------
## Method `Text$new`
## ------------------------------------------------
# Consider using text() instead.
txt <- Text$new()
## ------------------------------------------------
## Method `Text$get_translation`
## ------------------------------------------------
txt <- Text$new()
txt$set_translation("en", "Hello, world!")
txt$get_translation("en") ## Outputs "Hello, world!"
txt$get_translation("fr") ## Outputs NULL
## ------------------------------------------------
## Method `Text$set_translation`
## ------------------------------------------------
# Register a pair of source_lang and source_text.
txt <- Text$new()
txt$set_translation("en", "Hello, world!")
txt$source_lang <- "en"
## ------------------------------------------------
## Method `Text$set_translations`
## ------------------------------------------------
txt <- Text$new()
txt$set_translations(en = "Hello, world!", fr = "Bonjour, monde!")
## ------------------------------------------------
## Method `Text$set_locations`
## ------------------------------------------------
txt <- Text$new()
txt$set_locations(
location("a", 1L, 2L, 3L, 4L),
location("a", 1L, 2L, 3L, 4L),
location("b", 5L, 6L, 7L, 8L))
## ------------------------------------------------
## Method `Text$rm_translation`
## ------------------------------------------------
txt <- Text$new()
txt$set_translations(en = "Hello, world!", fr = "Bonjour, monde!")
txt$source_lang <- "en"
# Remove source_lang and source_text.
txt$source_lang <- "fr"
txt$rm_translation("en")
## ------------------------------------------------
## Method `Text$rm_location`
## ------------------------------------------------
txt <- Text$new()
txt$set_locations(
location("a", 1L, 2L, 3L, 4L),
location("b", 5L, 6L, 7L, 8L))
txt$rm_location("a")
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.