# Basic Translation Tutorial

{% hint style="info" %}
This tutorial shows you the basics of PixieBrix and will help you understand how to create a mod ([what's a mod?](https://www.pixiebrix.com/glossary/mod)), interact with an API, and display that response in the sidebar.

You'll learn how to : 

* Initiate or launch a mod
* Reference input from a starter brick
* Add bricks to a mod
* Make an API call in PixieBrix
* Reference output from a brick in other bricks
* Use Text Templates to inject dynamic values into text
* Create interactive displays with dynamic data (such as responses from APIs)
  {% endhint %}

This tutorial should take about 10 minutes. If you have any questions, click the purple live chat button in the bottom left corner or [reach out to support](mailto:support@pixiebrix.com).

![](/files/sk29j5hhEoFVmCbBwCxn)

{% hint style="warning" %}
If you get stuck and cannot move forward, [activate this mod](https://app.pixiebrix.com/activate?id%5B%5D=%40pixies%2Ftutorial%2Fbasic-translate) to see the final solution. Follow these docs if you need help [Activating Mods](/activating-mods.md). Once you've activated it, you'll find it in the Page Editor on the first panel, the [Mod Listing Panel](/platform-overview/page-editor/page-editor-components/mod-listing-panel.md).
{% endhint %}

### Prefer to watch? 

Watch the video for a walkthrough of this tutorial.

{% embed url="<https://youtube.com/live/M1qFXxmFyFs>" %}

Prefer the text version? Skip the video and keep reading!

### PreReqs

Before getting started, you'll need:&#x20;

* a PixieBrix account ([create a free one](https://app.pixiebrix.com/))
* the Page Editor open ([how?](/platform-overview/page-editor/open-the-page-editor.md))
* basic understanding of the terms we use to reference sections of the Page Editor ([learn more about those here](/platform-overview/page-editor/page-editor-components.md))

You're ready to start the tutorial if your screen looks something like this.&#x20;

<figure><img src="/files/UK5BCChXciniWDvwthfa" alt=""><figcaption></figcaption></figure>

At the end of each step, you'll see a 🏁 that shows you how to know if you're ready to move to the next step. There will be screenshots indicating how you should have configured the brick for that step.

### Step 1: Start your mod with a context menu brick

{% hint style="info" %}
Every mod begins with a Starter Brick, which is one of 5 types of mods that determine how and where a mod runs. *(Learn more about* [Types of Mods](/developing-mods/developer-concepts/types-of-mods.md)*.)*
{% endhint %}

For this mod, we'll use the Context Menu starter brick.&#x20;

#### 1.1 Add the context menu brick

To do this click the **New Mod** button in the top left of the Page Editor, then choose the **Context Menu** option. ([What's a context menu](/developing-mods/developer-concepts/types-of-mods/context-menu-item.md)?)

<figure><img src="/files/w0KqfhNkcV4jYZQSPaDT" alt=""><figcaption></figcaption></figure>

Once you click that, configuration options appear in the middle of your Page Editor, this is the [Brick Configuration Panel](/platform-overview/page-editor/page-editor-components/brick-configuration-panel.md).

#### 1.2 Update the Name and Title

The **Name** field is the mod component in the first panel, the Mod Listings Panel.

The **Title** is the text that appears on the context menu. You may call it something like "Greek Translate" (or whatever language you'd like to translate to). You can also dynamically show the selected text by including `%s` in the Title.

<figure><img src="/files/uKqLrOqlVCKBLENy2MFn" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
If a title starts with an emoji, it will appear on the Visual Popover element when you select text. ![](/files/6ANWcyAa9hWeMwbHFIEy)
{% endhint %}

#### 1.3 Change Menu context to selection

In the **Menu context** dropdown, choose `selection` and remove `all` by clicking the x after the text.

<figure><img src="/files/aodg5cvv76AtlAht4f3Z" alt=""><figcaption></figcaption></figure>

**This ensures the context menu action only appears when you have text selected.**&#x20;

{% hint style="danger" %}
Not seeing your context menu? Check that you've highlighted text on the page!
{% endhint %}

#### 1.4 Choose All URLs for Sites

Specify which sites you'd like to be able to run this mod on. By default, PixieBrix will set the current site, but if you want to run on any URL, click the **All URLs** option.

You can then remove the `docs.pixiebrix.com` url by clicking the ABC at the end of the field and choosing **X**.

#### 🏁 Checkpoint

You're ready to move on to the next step if your brick looks like this:

<figure><img src="/files/0k13USKpQucFfhXHjATA" alt=""><figcaption></figcaption></figure>

You should also see an emoji appear when text is selected, and appearing when you right-click on the page:

<figure><img src="/files/evPKB1Mr4bobvmc0ShKN" alt=""><figcaption></figcaption></figure>

Clicking that action runs the Brick Pipeline, so let's add more bricks.

### Step 2: Make an API Call&#x20;

Now that we can trigger our mod, we must tell it to do something. In this case, we want to connect to an API to translate the selected text.&#x20;

#### 2.1 Click the + button below Context Menu to add a brick

In the [Brick Actions Pipeline](/platform-overview/page-editor/page-editor-components/brick-actions-panel.md), you'll see a + icon just below the Context Menu brick. Click the **+ button** to open the **Add a Brick** modal.<br>

<figure><img src="/files/ecKpIlzwJKD1Mg5XQRLo" alt=""><figcaption></figcaption></figure>

#### 2.2 Add the Translate brick

Search for Translate and add this brick:

<figure><img src="/files/wH7MP4xO6oiXGzkT1vwH" alt=""><figcaption></figcaption></figure>

#### 2.3 Select the Built-In Google Translate integration

Click the integration field and select the Google Translate ✨ Built In option.&#x20;

#### 2.3 Set the text to translate to the selected text.&#x20;

In the "Text to Translate" field, type `@input.selectionText`to reference the text that was highlighted.&#x20;

#### 2.4 Set the translation language your desired language code

Set the Translate To Language to the language code you want to translate to. Want to stick with Greek? You can use \`el\`.

#### 2.5 Change the output variable to \`response\`

This will make it easier to reference later.&#x20;

#### 🏁 Checkpoint

You're ready to move on to the next step if your brick looks like this:

<figure><img src="/files/g7eJ13yl1Chr6ab46SaB" alt=""><figcaption></figcaption></figure>

### Step 3: View the output of your response

You're ready to run your mod and check the API returns the expected response.&#x20;

#### 3.1 Select text on the page above the Page Editor

Highlight text on the webpage, and click the globe emoji to run the mod.

<figure><img src="/files/Fd58Lz9YNZGjGztoq4mJ" alt=""><figcaption></figcaption></figure>

#### 3.2 View the Output in the Data Panel

You might have noticed some checkmarks appear next to brick in your [Brick Actions Panel ](/platform-overview/page-editor/page-editor-components/brick-actions-panel.md) (second panel in the Page Editor). This lets you know your steps succeeded.&#x20;

<figure><img src="/files/0zcYnfJdX19s1TcNUZOW" alt=""><figcaption></figcaption></figure>

Confirm you have selected the Translate brick (it will have a blue background in the Brick Actions Panel), then confirm you have selected the **Output** tab on the [**Data Panel**](/platform-overview/page-editor/page-editor-components/data-panel.md) (last panel on the right).

This is where you can view the response from the API. Click the **>** before `@response` to open the object and view the response.

This response can be used in any bricks that come afterward, giving you a way to provide dynamic values to other bricks, such as displaying the response. We'll do this in the next step.

#### 🏁 Checkpoint

You're ready to move on if you can successfully see the translatedText response in the Data Panel of your sidebar, like the screenshot above.&#x20;

If you have any errors, confirm you've configured your brick according to the screenshot in Step 2.

### Step 4: Display the Response in a Sidebar

Lastly, we will add a brick to display our response in a sidebar.

#### 4.1 Add the Display Temporary Information brick

Click the + button below the HTTP Response brick in the [Brick Actions Panel](/platform-overview/page-editor/page-editor-components/brick-actions-panel.md) and search for the Display Temporary Information brick. Hover over it, then click the blue **Add** button.

<figure><img src="/files/FX9Ie5xJ4dKdhJ6qmNZN" alt=""><figcaption></figcaption></figure>

You'll see that two bricks were added to your Brick Actions Panel:&#x20;

* Display Temporary Information
* Render Document

#### 4.2 Give the Display Temporary Information Brick a title

In the brick Configuration Panel for the Display Temporary Information Brick, rename the Title to `Translation`

<figure><img src="/files/Pfkv3RbOKwCnMyaRM8Sw" alt=""><figcaption></figcaption></figure>

You can also choose to move the location from Sidebar to a Modal or Popover. We'll leave this as a Sidebar.

#### 4.3 Click the Render Document brick in the Brick Actions Panel

Now, click the **Render Document** brick to style the Sidebar. Once you click the Render Document brick in the Brick Actions Panel, you'll see a preview appear on the far right panel (the [Data Panel](/platform-overview/page-editor/page-editor-components/data-panel.md))

<figure><img src="/files/V1UUhdMrclOWVLkqBdUf" alt=""><figcaption></figcaption></figure>

Click any element in the Preview panel to edit.&#x20;

#### 4.4 Rename Example Document to Translate

Click the **Example document** text on the Preview Panel, and the middle [Brick Configuration Panel](/platform-overview/page-editor/page-editor-components/brick-configuration-panel.md) will display options for modifying that element.&#x20;

<figure><img src="/files/jiZY53L7rFLHnww0oo5r" alt=""><figcaption></figcaption></figure>

In this case, the element is a Header type. So, the configuration options include the text itself, which you can rename in the Title field.

**Replace the text with "Translate" instead of "Example document".**&#x20;

You can also change the size of the header. There are other optional settings for styling and setting criteria to hide the element dynamically. You can leave these as is for this tutorial.&#x20;

#### 4.5 Replace the Example text element with the response

Now click the **Example text element** in the preview panel.&#x20;

New configuration options appear for the Text element. Replace the Text value with the following:

```
Your translated text: {{ @response.translatedText }}
```

Notice we can reference the output from the Translate brick by providing the variable path and wrapping it in `{{ }}` to inject the value in hardcoded strings.&#x20;

{% hint style="info" %}
You can access the property by using the variable popover, which displays available variables once you start typing `@`, or you can copy the path by viewing the output from the brick and clicking the copy icon next to the item you want to reference.
{% endhint %}

#### 🏁 Checkpoint

You're ready to move to the next step when your sidebar preview panel looks like this:&#x20;

<figure><img src="/files/2LY2UqCqHPueuFiy5JKH" alt=""><figcaption></figcaption></figure>

### Step 5: Save your mod and try it out

Your mod is built, so it's time to save and test it.&#x20;

#### 5.1 Click Save in the Mod Listing Panel

On the first panel on the left, the [Mod Listing Panel](/platform-overview/page-editor/page-editor-components/mod-listing-panel.md), click the **Save** icon on your translate mod.

<figure><img src="/files/ySjeQOweKT9fUSX5Y9fH" alt=""><figcaption></figcaption></figure>

You can now close your Page Editor and test out your mod!

#### 5.2 Select text, right-click, and choose the Translate action&#x20;

Select any text on the page (*like this paragraph!*), right-click, and then choose the Translate action.&#x20;

You should see a sidebar with your translated text a moment later.&#x20;

<figure><img src="/files/9B7jfMKOgx9FNJXTQQAn" alt=""><figcaption></figcaption></figure>

🎉 Congrats!! You just built a mod.&#x20;

{% hint style="info" %}
If it's not working, you can [activate the template](https://app.pixiebrix.com/activate?id%5B%5D=%40pixies%2Ftutorial%2Fbasic-translate) to see how it's meant to be structured, and compare your build to the template mod. You can also [reach out to our support team ](mailto:support@pixiebrix.com)or click the live chat button in the bottom left corner of this page.
{% 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://docs.pixiebrix.com/tutorials/developer-tutorials/beginner/basic-translation-tutorial.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.