# Multilingual texts

To use the multilingual text features of the [Locale](/version-0.x/reference/core-modules/locale.md) module, Cherrycake uses the `cherrycake_locale_texts` and `cherrycake_locale_textcategories` database tables with the following structure:

> You can create this tables in your database by importing the `locale.sql` file you'll find in the [Cherrycake skeleton repository](https://github.com/tin-cat/cherrycake-skeleton), under the `install/database` directory.

## Text categories

Optionally, texts in the database can be organized in categories, this might come in handy if you have lots of texts.

Add your text categories as rows to the `cherrycake_locale_textcategories` table, here's the columns specification:

* **`code`** A unique identifier for the category, you'll be using it later to refer to this category in your code.
* **`description`** Describe the kind of texts you'll be storing in this category.

## Adding texts

Add translated texts as rows to the `cherrycake_locale_texts` table, with this column specification:

* **`textCategories_id`** The category id assigned in the `cherrycake_locale_textcategories` table.
* **`code`** A unique identifier for the text, you'll be using it later to refer to this text in your code.
* **`description`** Describe this text, and the context where it will be used.
* **`text_en`** The text in english.

## Retrieving multilingual texts

To retrieve a text based on the current locale language, use the [Locale::getText](/version-0.x/reference/core-modules/locale/locale-methods.md#gettext) method. Imagine the `cherrycake_locale_textcategories` like this:

| id | code    | description                             |
| -- | ------- | --------------------------------------- |
| 1  | general | General texts used throughout the site. |

And the `cherrycake_locale_texts` tables like this:

| id | textCategories\_id | code | description                               | text\_en    | text\_es   |
| -- | ------------------ | ---- | ----------------------------------------- | ----------- | ---------- |
| 1  | 1                  | test | The typical test text used as an example. | Hello world | Hola mundo |

You would access the text like this:

```php
echo $e->Locale->getText("general/test");
$e->Locale->setLocale("spain");
echo $e->Locale->getText("general/test");
```

```
Hello world
Hola mundo
```

{% hint style="success" %}
See this example working in the [Cherrycake documentation examples](https://documentation-examples.cherrycake.io/example/localeGuideMultilingualTexts) site.
{% endhint %}

## Adding new languages

To add new languages, just add new columns to the cherrycake\_locale\_texts table. The column name must follow the syntax `text_<language code>` For example, to add a text field for spanish, add the a field named `text_es`.

## Variables in localized texts

You can use simple variables in localized texts to help you build more complex sentences, like this:

| textCategories\_id | code        | text\_en                                  | text\_es                                   |
| ------------------ | ----------- | ----------------------------------------- | ------------------------------------------ |
| 1                  | newMessages | You have {numberOfMessages} new messages. | Tienes {numberOfMessages} mensajes nuevos. |

```php
echo $e->Locale->getText("general/newMessages", [
    "variables" => [
        "numberOfMessages" => 5
    ]
]);
```

```
You have 5 new messages.
```

{% hint style="success" %}
See this example working in the [Cherrycake documentation examples](https://documentation-examples.cherrycake.io/example/localeGuideVariablesInMultilingualTexts) site.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://cherrycake.tin.cat/version-0.x/guide/locale-guide/multilingual-texts.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.