betty.locale package - Betty 0.4.0a3 documentation

Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
View this page
Toggle table of contents sidebar

# betty.locale package

## Submodules

- betty.locale.localizable module
  - `Localizable`
    - `Localizable.localize()`
  - `call()`
  - `format()`
  - `gettext()`
  - `ngettext()`
  - `npgettext()`
  - `pgettext()`
  - `plain()`

## Module contents

Provide the Locale API.

class betty.locale.Date

  Bases: `LinkedDataDumpable`

  A (Gregorian) date.

  Parameters:

    - year (`int` | `None`)

    - month (`int` | `None`)

    - day (`int` | `None`)

    - fuzzy (`bool`)

  __init__(year: int | None = None, month: int | None = None, day: int | None = None, fuzzy: bool = False)
    Parameters:

      - year (`int` | `None`)

      - month (`int` | `None`)

      - day (`int` | `None`)

      - fuzzy (`bool`)

  property comparable: bool

    If this date is comparable to other dateys.

  property complete: bool

    Whether this date is complete.

  async datey_dump_linked_data(dump: dict[str, bool | int | float | str | None | Sequence[bool | int | float | str | None | Sequence[Dump] | Mapping[str, Dump]] | Mapping[str, bool | int | float | str | None | Sequence[Dump] | Mapping[str, Dump]]], start_schema_org: str, end_schema_org: str) → None

    Dump this instance to JSON-LD for a ‘datey’ field.

    Parameters:

      - dump (`dict`[`str`, `typing.Union`[`bool`, `int`, `float`, `str`, `None`, `typing.Sequence`[`typing.Union`[`bool`, `int`, `float`, `str`, `None`, `typing.Sequence`[Dump], `typing.Mapping`[`str`, Dump]]], `typing.Mapping`[`str`, `typing.Union`[`bool`, `int`, `float`, `str`, `None`, `typing.Sequence`[Dump], `typing.Mapping`[`str`, Dump]]]]])

      - start_schema_org (`str`)

      - end_schema_org (`str`)

    Return type:

      `None`

  day: `int` | `None`
  async dump_linked_data(project: betty.project.Project, schemas_org: list[str] | None = None) → dict[str, bool | int | float | str | None | Sequence[bool | int | float | str | None | Sequence[Dump] | Mapping[str, Dump]] | Mapping[str, bool | int | float | str | None | Sequence[Dump] | Mapping[str, Dump]]]

    Dump this instance to JSON-LD.

    Parameters:

      - project (`betty.project.Project`)

      - schemas_org (`list`[`str`] | `None`)

    Return type:

      `dict`[`str`, `typing.Union`[`bool`, `int`, `float`, `str`, `None`, `typing.Sequence`[`typing.Union`[`bool`, `int`, `float`, `str`, `None`, `typing.Sequence`[Dump], `typing.Mapping`[`str`, Dump]]], `typing.Mapping`[`str`, `typing.Union`[`bool`, `int`, `float`, `str`, `None`, `typing.Sequence`[Dump], `typing.Mapping`[`str`, Dump]]]]]

  fuzzy: `bool`
  async classmethod linked_data_schema(project: betty.project.Project) → dict[str, bool | int | float | str | None | Sequence[bool | int | float | str | None | Sequence[Dump] | Mapping[str, Dump]] | Mapping[str, bool | int | float | str | None | Sequence[Dump] | Mapping[str, Dump]]]

    Define the JSON Schema for `betty.json.linked_data.LinkedDataDumpable.dump_linked_data()`.

    Parameters:

      project (`betty.project.Project`)

    Return type:

      `dict`[`str`, `typing.Union`[`bool`, `int`, `float`, `str`, `None`, `typing.Sequence`[`typing.Union`[`bool`, `int`, `float`, `str`, `None`, `typing.Sequence`[Dump], `typing.Mapping`[`str`, Dump]]], `typing.Mapping`[`str`, `typing.Union`[`bool`, `int`, `float`, `str`, `None`, `typing.Sequence`[Dump], `typing.Mapping`[`str`, Dump]]]]]

  month: `int` | `None`
  property parts: tuple[int | None, int | None, int | None]

    The date parts: a 3-tuple of the year, month, and day.

  to_range() → betty.locale.DateRange

    Convert this date to a date range.

    Return type:

      `betty.locale.DateRange`

  year: `int` | `None`

class betty.locale.DateRange

  Bases: `LinkedDataDumpable`

  A date range can describe a period of time between, before, after, or around start and/or end dates.

  Parameters:

    - start (`betty.locale.Date` | `None`)

    - end (`betty.locale.Date` | `None`)

    - start_is_boundary (`bool`)

    - end_is_boundary (`bool`)

  __init__(start: betty.locale.Date | None = None, end: betty.locale.Date | None = None, start_is_boundary: bool = False, end_is_boundary: bool = False)
    Parameters:

      - start (`betty.locale.Date` | `None`)

      - end (`betty.locale.Date` | `None`)

      - start_is_boundary (`bool`)

      - end_is_boundary (`bool`)

  property comparable: bool

    If this date is comparable to other dateys.

  async datey_dump_linked_data(dump: dict[str, bool | int | float | str | None | Sequence[bool | int | float | str | None | Sequence[Dump] | Mapping[str, Dump]] | Mapping[str, bool | int | float | str | None | Sequence[Dump] | Mapping[str, Dump]]], start_schema_org: str, end_schema_org: str) → None

    Dump this instance to JSON-LD for a ‘datey’ field.

    Parameters:

      - dump (`dict`[`str`, `typing.Union`[`bool`, `int`, `float`, `str`, `None`, `typing.Sequence`[`typing.Union`[`bool`, `int`, `float`, `str`, `None`, `typing.Sequence`[Dump], `typing.Mapping`[`str`, Dump]]], `typing.Mapping`[`str`, `typing.Union`[`bool`, `int`, `float`, `str`, `None`, `typing.Sequence`[Dump], `typing.Mapping`[`str`, Dump]]]]])

      - start_schema_org (`str`)

      - end_schema_org (`str`)

    Return type:

      `None`

  async dump_linked_data(project: betty.project.Project, start_schema_org: str | None = None, end_schema_org: str | None = None) → dict[str, bool | int | float | str | None | Sequence[bool | int | float | str | None | Sequence[Dump] | Mapping[str, Dump]] | Mapping[str, bool | int | float | str | None | Sequence[Dump] | Mapping[str, Dump]]]

    Dump this instance to JSON-LD.

    Parameters:

      - project (`betty.project.Project`)

      - start_schema_org (`str` | `None`)

      - end_schema_org (`str` | `None`)

    Return type:

      `dict`[`str`, `typing.Union`[`bool`, `int`, `float`, `str`, `None`, `typing.Sequence`[`typing.Union`[`bool`, `int`, `float`, `str`, `None`, `typing.Sequence`[Dump], `typing.Mapping`[`str`, Dump]]], `typing.Mapping`[`str`, `typing.Union`[`bool`, `int`, `float`, `str`, `None`, `typing.Sequence`[Dump], `typing.Mapping`[`str`, Dump]]]]]

  end: `betty.locale.Date` | `None`
  end_is_boundary: `bool`
  async classmethod linked_data_schema(project: betty.project.Project) → dict[str, bool | int | float | str | None | Sequence[bool | int | float | str | None | Sequence[Dump] | Mapping[str, Dump]] | Mapping[str, bool | int | float | str | None | Sequence[Dump] | Mapping[str, Dump]]]

    Define the JSON Schema for `betty.json.linked_data.LinkedDataDumpable.dump_linked_data()`.

    Parameters:

      project (`betty.project.Project`)

    Return type:

      `dict`[`str`, `typing.Union`[`bool`, `int`, `float`, `str`, `None`, `typing.Sequence`[`typing.Union`[`bool`, `int`, `float`, `str`, `None`, `typing.Sequence`[Dump], `typing.Mapping`[`str`, Dump]]], `typing.Mapping`[`str`, `typing.Union`[`bool`, `int`, `float`, `str`, `None`, `typing.Sequence`[Dump], `typing.Mapping`[`str`, Dump]]]]]

  start: `betty.locale.Date` | `None`
  start_is_boundary: `bool`

exception betty.locale.IncompleteDateError

  Bases: `ValueError`

  Raised when a datey was unexpectedly incomplete.

exception betty.locale.LocaleNotFoundError

  Bases: `RuntimeError`

  Raise when a locale could not be found.

  Parameters:

    locale (`str`)

  __init__(locale: str) → None
    Parameters:

      locale (`str`)

class betty.locale.Localized

  Bases: `LinkedDataDumpable`

  A resource that is localized, e.g. contains information in a specific locale.

  Parameters:

    - args (`typing.Any`)

    - locale (`str` | `None`)

    - kwargs (`typing.Any`)

  __init__(*args: Any, locale: str | None = None, **kwargs: Any)
    Parameters:

      - args (`typing.Any`)

      - locale (`str` | `None`)

      - kwargs (`typing.Any`)

  async dump_linked_data(project: betty.project.Project) → dict[str, bool | int | float | str | None | Sequence[bool | int | float | str | None | Sequence[Dump] | Mapping[str, Dump]] | Mapping[str, bool | int | float | str | None | Sequence[Dump] | Mapping[str, Dump]]]

    Dump this instance to JSON-LD.

    Parameters:

      project (`betty.project.Project`)

    Return type:

      `dict`[`str`, `typing.Union`[`bool`, `int`, `float`, `str`, `None`, `typing.Sequence`[`typing.Union`[`bool`, `int`, `float`, `str`, `None`, `typing.Sequence`[Dump], `typing.Mapping`[`str`, Dump]]], `typing.Mapping`[`str`, `typing.Union`[`bool`, `int`, `float`, `str`, `None`, `typing.Sequence`[Dump], `typing.Mapping`[`str`, Dump]]]]]

  async classmethod linked_data_schema(project: betty.project.Project) → dict[str, bool | int | float | str | None | Sequence[bool | int | float | str | None | Sequence[Dump] | Mapping[str, Dump]] | Mapping[str, bool | int | float | str | None | Sequence[Dump] | Mapping[str, Dump]]]

    Define the JSON Schema for `betty.json.linked_data.LinkedDataDumpable.dump_linked_data()`.

    Parameters:

      project (`betty.project.Project`)

    Return type:

      `dict`[`str`, `typing.Union`[`bool`, `int`, `float`, `str`, `None`, `typing.Sequence`[`typing.Union`[`bool`, `int`, `float`, `str`, `None`, `typing.Sequence`[Dump], `typing.Mapping`[`str`, Dump]]], `typing.Mapping`[`str`, `typing.Union`[`bool`, `int`, `float`, `str`, `None`, `typing.Sequence`[Dump], `typing.Mapping`[`str`, Dump]]]]]

  locale: `str` | `None`

class betty.locale.Localizer

  Bases: `object`

  Provide localization functionality for a specific locale.

  Parameters:

    - locale (`str`)

    - translations (`gettext.NullTranslations`)

  __init__(locale: str, translations: gettext.NullTranslations)
    Parameters:

      - locale (`str`)

      - translations (`gettext.NullTranslations`)

  format_date(date: betty.locale.Date) → str

    Format a date to a human-readable string.

    Parameters:

      date (`betty.locale.Date`)

    Return type:

      `str`

  format_date_range(date_range: betty.locale.DateRange) → str

    Format a date range to a human-readable string.

    Parameters:

      date_range (`betty.locale.DateRange`)

    Return type:

      `str`

  format_datetime_datetime(datetime_datetime: datetime.datetime) → str

    Format a datetime date to a human-readable string.

    Parameters:

      datetime_datetime (`datetime.datetime`)

    Return type:

      `str`

  format_datey(date: betty.locale.Date | betty.locale.DateRange) → str

    Format a datey value into a human-readable string.

    Parameters:

      date (`betty.locale.Date` | `betty.locale.DateRange`)

    Return type:

      `str`

  gettext(message: str) → str

    Like `gettext.gettext()`.

    Arguments are identical to those of `gettext.gettext()`.

    Parameters:

      message (`str`)

    Return type:

      `str`

  property locale: str

    The locale.

  ngettext(message_singular: str, message_plural: str, n: int) → str

    Like `gettext.ngettext()`.

    Arguments are identical to those of `gettext.ngettext()`.

    Parameters:

      - message_singular (`str`)

      - message_plural (`str`)

      - n (`int`)

    Return type:

      `str`

  npgettext(context: str, message_singular: str, message_plural: str, n: int) → str

    Like `gettext.npgettext()`.

    Arguments are identical to those of `gettext.npgettext()`.

    Parameters:

      - context (`str`)

      - message_singular (`str`)

      - message_plural (`str`)

      - n (`int`)

    Return type:

      `str`

  pgettext(context: str, message: str) → str

    Like `gettext.pgettext()`.

    Arguments are identical to those of `gettext.pgettext()`.

    Parameters:

      - context (`str`)

      - message (`str`)

    Return type:

      `str`

final class betty.locale.LocalizerRepository

  Bases: `object`

  Exposes the available localizers.

  Parameters:

    assets (`betty.assets.AssetRepository`)

  __init__(assets: betty.assets.AssetRepository)
    Parameters:

      assets (`betty.assets.AssetRepository`)

  async coverage(locale: str | babel.core.Locale) → tuple[int, int]

    Get the translation coverage for the given locale.

    Return type:

      `tuple`[`int`, `int`]

    Returns:

      A 2-tuple of the number of available translations and the number of translatable source strings.

    Parameters:

      locale (`str` | `babel.core.Locale`)

  async get(locale: str | babel.core.Locale) → betty.locale.Localizer

    Get the localizer for the given locale.

    Parameters:

      locale (`str` | `babel.core.Locale`)

    Return type:

      `betty.locale.Localizer`

  async get_negotiated(*preferred_locales: str) → betty.locale.Localizer

    Get the best matching available locale for the given preferred locales.

    Parameters:

      preferred_locales (`str`)

    Return type:

      `betty.locale.Localizer`

  property locales: Iterator[str]

    The available locales.

betty.locale.get_data(locale: str | babel.core.Locale) → babel.core.Locale

  Get locale metadata.

  Parameters:

    locale (`str` | `babel.core.Locale`)

  Return type:

    `babel.core.Locale`

betty.locale.get_display_name(locale: str | babel.core.Locale, display_locale: str | babel.core.Locale | None = None) → str | None

  Return a locale’s human-readable display name.

  Parameters:

    - locale (`str` | `babel.core.Locale`)

    - display_locale (`str` | `babel.core.Locale` | `None`)

  Return type:

    `str` | `None`

async betty.locale.init_translation(locale: str) → None

  Initialize a new translation.

  Parameters:

    locale (`str`)

  Return type:

    `None`

betty.locale.negotiate_locale(preferred_locales: str | babel.core.Locale | Sequence[str | babel.core.Locale], available_locales: Sequence[str | babel.core.Locale]) → babel.core.Locale | None

  Negotiate the preferred locale from a sequence.

  Parameters:

    - preferred_locales (`typing.Union`[`str`, `babel.core.Locale`, `typing.Sequence`[`str` | `babel.core.Locale`]])

    - available_locales (`typing.Sequence`[`str` | `babel.core.Locale`])

  Return type:

    `babel.core.Locale` | `None`

betty.locale.negotiate_localizeds(preferred_locales: str | babel.core.Locale | Sequence[str | babel.core.Locale], localizeds: Sequence[betty.locale.Localized]) → betty.locale.Localized | None

  Negotiate the preferred localized value from a sequence.

  Parameters:

    - preferred_locales (`typing.Union`[`str`, `babel.core.Locale`, `typing.Sequence`[`str` | `babel.core.Locale`]])

    - localizeds (`typing.Sequence`[`betty.locale.Localized`])

  Return type:

    `betty.locale.Localized` | `None`

async betty.locale.ref_date(root_schema: dict[str, bool | int | float | str | None | Sequence[bool | int | float | str | None | Sequence[Dump] | Mapping[str, Dump]] | Mapping[str, bool | int | float | str | None | Sequence[Dump] | Mapping[str, Dump]]], project: betty.project.Project) → dict[str, bool | int | float | str | None | Sequence[bool | int | float | str | None | Sequence[Dump] | Mapping[str, Dump]] | Mapping[str, bool | int | float | str | None | Sequence[Dump] | Mapping[str, Dump]]]

  Reference the Date schema.

  Parameters:

    - root_schema (`dict`[`str`, `typing.Union`[`bool`, `int`, `float`, `str`, `None`, `typing.Sequence`[`typing.Union`[`bool`, `int`, `float`, `str`, `None`, `typing.Sequence`[Dump], `typing.Mapping`[`str`, Dump]]], `typing.Mapping`[`str`, `typing.Union`[`bool`, `int`, `float`, `str`, `None`, `typing.Sequence`[Dump], `typing.Mapping`[`str`, Dump]]]]])

    - project (`betty.project.Project`)

  Return type:

    `dict`[`str`, `typing.Union`[`bool`, `int`, `float`, `str`, `None`, `typing.Sequence`[`typing.Union`[`bool`, `int`, `float`, `str`, `None`, `typing.Sequence`[Dump], `typing.Mapping`[`str`, Dump]]], `typing.Mapping`[`str`, `typing.Union`[`bool`, `int`, `float`, `str`, `None`, `typing.Sequence`[Dump], `typing.Mapping`[`str`, Dump]]]]]

async betty.locale.ref_date_range(root_schema: dict[str, bool | int | float | str | None | Sequence[bool | int | float | str | None | Sequence[Dump] | Mapping[str, Dump]] | Mapping[str, bool | int | float | str | None | Sequence[Dump] | Mapping[str, Dump]]], project: betty.project.Project) → dict[str, bool | int | float | str | None | Sequence[bool | int | float | str | None | Sequence[Dump] | Mapping[str, Dump]] | Mapping[str, bool | int | float | str | None | Sequence[Dump] | Mapping[str, Dump]]]

  Reference the DateRange schema.

  Parameters:

    - root_schema (`dict`[`str`, `typing.Union`[`bool`, `int`, `float`, `str`, `None`, `typing.Sequence`[`typing.Union`[`bool`, `int`, `float`, `str`, `None`, `typing.Sequence`[Dump], `typing.Mapping`[`str`, Dump]]], `typing.Mapping`[`str`, `typing.Union`[`bool`, `int`, `float`, `str`, `None`, `typing.Sequence`[Dump], `typing.Mapping`[`str`, Dump]]]]])

    - project (`betty.project.Project`)

  Return type:

    `dict`[`str`, `typing.Union`[`bool`, `int`, `float`, `str`, `None`, `typing.Sequence`[`typing.Union`[`bool`, `int`, `float`, `str`, `None`, `typing.Sequence`[Dump], `typing.Mapping`[`str`, Dump]]], `typing.Mapping`[`str`, `typing.Union`[`bool`, `int`, `float`, `str`, `None`, `typing.Sequence`[Dump], `typing.Mapping`[`str`, Dump]]]]]

async betty.locale.ref_datey(root_schema: dict[str, bool | int | float | str | None | Sequence[bool | int | float | str | None | Sequence[Dump] | Mapping[str, Dump]] | Mapping[str, bool | int | float | str | None | Sequence[Dump] | Mapping[str, Dump]]], project: betty.project.Project) → dict[str, bool | int | float | str | None | Sequence[bool | int | float | str | None | Sequence[Dump] | Mapping[str, Dump]] | Mapping[str, bool | int | float | str | None | Sequence[Dump] | Mapping[str, Dump]]]

  Reference the Datey schema.

  Parameters:

    - root_schema (`dict`[`str`, `typing.Union`[`bool`, `int`, `float`, `str`, `None`, `typing.Sequence`[`typing.Union`[`bool`, `int`, `float`, `str`, `None`, `typing.Sequence`[Dump], `typing.Mapping`[`str`, Dump]]], `typing.Mapping`[`str`, `typing.Union`[`bool`, `int`, `float`, `str`, `None`, `typing.Sequence`[Dump], `typing.Mapping`[`str`, Dump]]]]])

    - project (`betty.project.Project`)

  Return type:

    `dict`[`str`, `typing.Union`[`bool`, `int`, `float`, `str`, `None`, `typing.Sequence`[`typing.Union`[`bool`, `int`, `float`, `str`, `None`, `typing.Sequence`[Dump], `typing.Mapping`[`str`, Dump]]], `typing.Mapping`[`str`, `typing.Union`[`bool`, `int`, `float`, `str`, `None`, `typing.Sequence`[Dump], `typing.Mapping`[`str`, Dump]]]]]

async betty.locale.run_babel(*args: str) → None

  Run a Babel Command Line Interface (CLI) command.

  Parameters:

    args (`str`)

  Return type:

    `None`

betty.locale.to_babel_identifier(locale: str | babel.core.Locale) → str

  Convert a locale or locale metadata to a Babel locale identifier.

  Parameters:

    locale (`str` | `babel.core.Locale`)

  Return type:

    `str`

betty.locale.to_locale(locale: str | babel.core.Locale) → str

  Ensure that a locale or locale metadata is a locale.

  Parameters:

    locale (`str` | `babel.core.Locale`)

  Return type:

    `str`

async betty.locale.update_translations(_output_assets_directory_path: pathlib.Path = PosixPath('/home/runner/work/betty/betty/betty/assets')) → None

  Update all existing translations based on changes in translatable strings.

  Parameters:

    _output_assets_directory_path (`pathlib.Path`)

  Return type:

    `None`