What is Transcribe?

Transcribe is an ExpressionEngine 2 module which adds multi-lingual functionality to ExpressionEngine and simplifies the creation and management of multi-lingual websites.

Installation

Once you've downloaded and extracted Transcribe for ExpressionEngine 2, copy the 'system/expressionengine/third_party/transcribe' directory into the 'system/expressionengine/third_party/transcribe' directory of your ExpressionEngine installation.

Next, log into your ExpressionEngine control panel and install the module and the extension from the 'Modules' section.

Getting Started

To start using Transcribe, you will need to define a language to use. Seeing as you just installed the module, Transcribe will ask you to define a language before you can use it. We also give you the option to assign all current entries to the first language you create. This makes it easy to get the initial language setup in case you are adding multi-lingual capability to an existing site.

Once you've defined a language or multiple languages to use for this site you will be able to create a variety of translated content. Below you will learn how to create translated content for templates, for single words or phrases and for channel entries.

Languages

Languages is the top tier that defines and separates translated content. To support more languages, you will need to define them here and in doing so can identify translated entries and words/phrases with a language. This allows Transcribe to quickly determine what content needs to be loaded for the currently selected language.

Variables

Variables are little words and/or phrases throughout your website that need to be translated when the language changes.

To begin creating Variables for Transcribe, select the language and site from the Languages box to define where these new variables will be assigned. Click View to update that info.

When creating a new variable, you will need to assign a name to it and the translated content that will be associated. Click Add Row to continue adding new variables. If you've already created variables in other languages, you can select them from the drop-down instead of writing it into the textfield.

When you are done adding variables, click Save to save everything.

To use the variables you've just created in your templates, you can use the Transcribe translate or replace tag:

<a href="#">{exp:transcribe:replace name="nav_home"}</a>
OR
<a href="#">{exp:transcribe:translate name="nav_home"}Home{/exp:transcribe:translate}</a>

Templates

Transcribe will also handle translating url's throughout your website. To aid in this, you will need to provide translations to all of your web accessible templates and groups. To begin, select the language and site from the Languages box to define which language these translated templates and groups will be assigned. Click View to update that info.

You will be brought to the same page with the new language you've selected. Go ahead and fill in the translations for all the web accessible templates and groups. When you are done, click Save.

Now, you will need to replace all {path=""} tags with {exp:transcribe:uri path=""} for transcribe to translate the urls on the fly.

Channel Entries

Translating your channel entry data is also very easy. When publishing a new entry, you will see a new tab labeled 'Transcribe'.

On this tab you can associate which language this new entry will be assigned to. Once you save this entry, return to the edit screen and click the Transcribe tab again and you will see another section labeled 'Associated Entries'. Associated Entries is a list of all the translations of this entry. If one does no exist, click the language and you will be brought to a new publish page where you can create it.

You do not have to associate translations with every entry. You can just assign the language to a new entry and it will show for that language only.

Language Switcher

Transcribe provides a tag you can use to create a custom language switcher: language_links. Below are two examples of how you could use it:

Example as drop-down:

<form action="{exp:transcribe:action_url}" method="post">
    {exp:transcribe:language_links}
        <select name="lang">
            {languages}
                <option value="{abbreviation}"{if current} selected="selected"{/if}>{name}</option>
            {/languages}
        </select>
    {/exp:transcribe:language_links}

    <input type="submit" name="submit" value="Submit" />
</form>

Example as links list:

{exp:transcribe:language_links}
    <ul>
        {languages}
            <li><a href="{link}"{if current} class="active"{/if}>{name}</a></li>
        {/languages}
    </ul>
{/exp:transcribe:language_links}

If you are running into an issue with restricted characters in the URI, you will need to append '=&' to the value of $config['permitted_uri_chars'] in the control panel.

Disable Transcribe

There are currently two different methods of disabling Transcribe.

The first method is on a per site basis, which can be set by going to the Settings page in Transcribe and setting "Transcribe enabled?" to "No". This will disable Transcribe for the given site.

Alternatively you can disable Transcribe on a per channel:entries basis in your templates by simply adding the transcribe="disable" paramater to your channel entries tag.

Categories

To create translations for categories, you will need to make Transcribe variables for each category. We recommending prefixing each variable with 'category_' so you can find it easily. You can either use the category id or the url title for the variable name like so: 'category_21' or 'category_my-category-name'

In your template where you are using the categories tag you would want to use {exp:transcribe:replace name="category_{category_id}"} or {exp:transcribe:replace name="category_{category_url_title}"} depending on how you named your variables.

Settings

There are two options you can set for each site in your ExpressionEngine install. The default language is the language you would like to load by default if the user hasn't specified the language (using the language switcher). You also have the option to include the language abbreviation as a prefix on the url. For instance, if this is set to 'yes' and the user has selected the English language, your urls would be re-written like this: http://mywebsite.com/en/about from http://mywebsite.com/about.

Tag Reference

Translate Tag:

{exp:transcribe:translate}Content to replace{/exp:transcribe:translate}

Parameters:

id = the variable id to use
name = the variable name to use

This tag pair replaces the content between the tags with the translated content variable of the current language with the id or name specified. If a variable isn't found in the selected language, Transcribe will fallback to the content between the tag pair.

Replace Tag:

{exp:transcribe:replace}

Parameters:

id = the variable id to use
name = the variable name to use

Outputs the translated content variable of the current language with the id or name specified.

Language Tag:

{exp:transcribe:language}

Parameters:

id = the language id to use
name = the language name to use

Sets the language to be used from the template. This can be used to override the default behavior of Transcribe which is to figure out what language to load automatically.

Language Abbreviation Tag:

{exp:transcribe:language_abbreviation}

Returns the abbreviation of the current language. Useful for front-end (HTML/CSS) development.

URI Tag:

{exp:transcribe:uri}

Parameters:

path = the path to output

Outputs the path specified in it's translated state for the current language. Used as a replacement to {path=""}.

Language_Links Tag:

{exp:transcribe:language_links}

Variables:

id = id of the language
name = name of the language
abbreviation = abbreviation of the language
link = link to the action url to switch to the language
current = true if this language is the currently selected language; false otherwise.

Retrieve an array of available languages for the current site. Can be used in the template to create a language switcher.