To get started, you’ll want to copy the Translation Mod Template so you can customize and build as we go!

📋 Make a copy of the Translation Mod Template

‍Before you can customize, you'll need to get the template in an editable format.

1. Activate the Mod Template.
2. Open the Page Editor.

In the Page Editor, click the three dot menu next to the activated template. In the menu, select Make a Copy

You might be asked to create an alias if this is your first time copying a mod.

Optional: You can change the Mod ID, Name, and Description fields in the modal that appears

Once you've customized, choose from one or more of the following changes you'd like to make.

🤖 Use a different translation API

This mod currently uses the Google Translate API to translate text, but you might prefer to use another translation API. It’s easy to switch.

Remove the Google Translate brick and add the HTTP Request brick in its place.

Use this brick to create your HTTP request with your preferred API.

You’ll need to:

• Set the endpoint URL
• Choose the method (likely fetch, but confirm with the API documentation)
• Click the “X” then “Object Properties” to add parameters to your request. (This is likely where you’ll pass the text to translate as well as the target translation language. To reference the selected text, use the variable @input.selectionText and to reference the target language use @options.target.)
• Use the Headers if needed to provide authentication or other API requirements
• You’ll likely leave JSON Data blank, unless your API requires a POST method for translating text

Check your response

Run your mod by selecting text and right-clicking on the page, then choosing the Translate This Text action. Check the output of the HTTP Request brick (far right panel) and click the caret to confirm you have a successful response with the expected data. Click the copy icon next to the response field that includes translated text.

Update the response in the sidebar

Lastly, you’ll use copied path to reference your translated text in your sidebar.

Click the Render Document brick from the Brick Actions pipeline.

Click {{@translated.translatedText}} in the Preview Panel on the far right side. In the middle panel that appears, replace the Text value with your copied path that has the translated response from your API.

Run your mod once again to check the response is displayed correctly.

Select a different target language when running

In some cases, you may not always want to use the same target language and may need to translate to a different language when running the mod. We'll need to set up page state handling, update target language references to look at the page state, and create a form to allow a user to set up other languages. Go through the following steps to do this.

The order in which you go through the following steps doesn't particularly matter, but do you need to complete them all or your mod will not work properly.

Set a default page state

Since the target language may change while using the mod, you'll need to keep track of the current target language with page state. Start by setting a default page

Click the + button just after the Context Menu brick (first brick) in the Brick Actions pipeline. Choose the Set shared page state brick.

Inside the Data object, click the blue Add Property button and make a property named language with a value of @options.language.

This will make sure the mod sets the default to the configured language when it runs so there's never an empty value for the the target language.

‍

Change the Refresh Trigger on Display Temporary Information

The Display Temporary Information brick comes with a handy event listener that can watch for state changes and refresh the content in the sidebar. This is incredibly useful for building dynamic sidebars that allow interaction.

To enable this, click the Display Temporary Information brick from the Brick Actions panel and then change the Refresh Trigger to Mod Variable/Page State Changed.

Now anytime the page state changes, the content will re-render. PixieBrix has a form element that can be added to the sidebar that saves responses to the state, creating a change, which makes it easy to create a dynamic sidebar by adding a form element. Let's do that now.

Add a Custom Form In the Sidebar

To add a custom form to the Sidebar, click the Render Document brick nested inside the Display Temporary Information brick.

Click the three-dot menu on the Translated Text element, and choose Form.

‍

You'll notice a new Form section appears in your Brick Actions pipeline (second panel from the left). Click the Custom Form brick inside that section.

Change the Auto Save field to True by clicking the X at the end of the row, selecting Toggle, and then clicking the Toggle to turn it to blue.

Scroll down to the Current Field section and edit the example field.

• Name: language
• Label: Translate to another language
• Field Description: click ABC then Exclude, otherwise change to whatever you'd like
• Input Type: Dropdown
• Options: Click Add Item and create a few options. 🚨 Important! Make sure any that you add match the Property name field in the Map/Lookup Value brick

‍

Fetch Page State before mapping and translating

Next we need to make sure our mod checks for the current state before doing a translation to ensure it translates to the preferred language.

To do this, add the Get shared page state brick in the body section of the Display Temporary Information brick, just above the Map/Lookup Value brick.

This will fetch the current page state. Now we need to set up our map brick to look at the page state instead of the configured default language.

Update Map brick to look at Page State, not options

Click on the Map/Lookup Value brick and change the key from @options.langage to @state.language.

That's an easy fix ✅

The last step is save your mod. PixieBrix will keep unsaved changes in the Page Editor, but for the changes to take affect when using the mod, you'll need to save. Click the save icon next to your mod to save the changes.

‍

‍

Test your mod

Now test your mod to confirm it works! Highlight some text on a page, right-click and choose the action from the context menu. If you didn't rename it, then it's probably going to be 🏜️ Translate This Text.

A sidebar will appear with text automatically translated to your target language, but you'll see a dropdown field near the translation. Click that to select another language and you should see the translation update in real time! 🎉

Congrats! You did it! Need any help? Join the PixieBrix Community Slack and we're happy to help troubleshoot any problems, show you how to add more features, or inspire your next build!

‍

‍