Understanding & Creating Custom XF Language Packs

XenForo (XF) provides robust tools for managing and translating your forum's interface. Whether you want to fine-tune existing English phrases, translate your forum into a new language, or create a regional variant, understanding how language packs work is crucial. This guide will walk you through the process of creating and managing custom language packs.

What is a Language Pack?

Essentially, a language pack is a collection of "phrases" – small snippets of text that make up the user interface. These can be anything from button labels ("Save," "Reply") to navigation links ("Forums," "Members") or error messages. Each phrase has a unique identifier, and the language pack provides the translated text for that identifier.

Why Create a Custom Language Pack?

• New Language Support: Translate your forum into a language not officially supported or fully translated by the community.
• Regional Variations: Adapt an existing language (e.g., "English (US)" vs. "English (UK)") for specific regional nuances.
• Custom Terminology: Change default XF phrases to better suit your community's specific jargon or branding.
• Correcting Errors: Fix typos or improve grammar in existing translations.
• Add-on Translations: Provide translations for third-party add-ons that may not include your desired language.

Prerequisites

Before you start, ensure you have:

• A running XenForo installation.
• Administrator access to your XenForo Control Panel (Admin CP).
• A text editor (for simple phrase editing) or a CAT (Computer-Assisted Translation) tool (for large-scale translation projects).

Core Concepts

1. Phrases: Every piece of visible text in XF is a phrase. They are identified by a unique phrase_key.
2. Parent/Child Languages: Languages in XF can inherit phrases from a "parent" language. This is incredibly useful. If a phrase isn't translated in a child language, XF falls back to the parent language's version. This prevents untranslated areas from appearing blank and simplifies updates. For example, "French" might be a child of "English (US)".
3. Language ID: Each language has a unique numeric ID.

Method 1: Editing Existing Phrases via Admin CP (For Minor Adjustments)

This is the easiest way to modify a few phrases in an existing language.

1. Navigate to Languages: In your Admin CP, go to Appearance > Languages.
2. Select Your Language: Click on the title of the language you wish to modify (e.g., "English (US)").
3. Search for Phrases:
* Use the "Search phrases" box. You can search by phrase_key, text (the actual displayed text), or even the addon_id if you know which add-on a phrase belongs to.
* For example, if you want to change "Log in", search for "Log in" in the "Text" field.
4. Edit the Phrase:
* Once you find the phrase, click the "Edit" button next to it.
* Modify the Phrase text field.
* Click "Save".
5. Revert Phrases: If you make a mistake, you can always revert a custom phrase back to its original value by clicking the "Revert" button. This is only available for phrases you've modified.

Pro Tip: When searching for phrases, you can choose to display "Customized phrases only" to see all the changes you've made to a specific language.

Method 2: Creating a New Language Pack (For Major Translation Efforts or New Languages)

This method is for when you need to translate a significant portion of the forum or introduce a completely new language.

Step 1: Create the New Language Shell

1. Go to Languages: In your Admin CP, navigate to Appearance > Languages.
2. Create New Language: Click the "+ Add language" button.
3. Configure Language Properties:
* Title: The name of your language (e.g., "Français (Canada)", "Deutsch").
* Language code: An ISO-standard language code (e.g., fr-CA, de, es). This is crucial for browser detection and SEO.
* Text direction: LTR (Left-to-Right) for most languages, RTL (Right-to-Left) for Arabic, Hebrew, etc.
* Date format/Time format: Adjust as necessary for your locale.
* Decimal separator/Thousands separator: Set according to your language's conventions.
* Parent language: Crucially, select the language you want to inherit phrases from (e.g., "English (US)"). This will be your base.
* User selectable: Check this if you want users to be able to choose this language.
4. Save the Language. You now have an empty language shell that inherits all phrases from its parent.

Step 2: Export Phrases for Translation

Now you need to get the phrases out of XenForo so you can translate them.

1. Select Parent Language: Go back to Appearance > Languages and click on your parent language (e.g., "English (US)").
2. Export Language: Scroll down and click the "Export language" button.
3. Export Options:
* Export type:
* All phrases: Exports every single phrase. Use this for a full translation project.
* Customized phrases only: Exports only phrases that have been modified in the *parent* language.
* Untranslated phrases only: (Less common for exporting from parent, more for child languages).
* Format:
* XenForo Language XML (.xml): This is the standard XF format for language packs. It's an older format but still works.
* XLIFF 1.2 (.xlf): Recommended for large translation projects. XLIFF is an industry-standard XML format for exchanging translation data, compatible with most CAT tools.
* CSV (.csv): A simple comma-separated values file, easy to open in spreadsheets, but less robust for complex translations.
* Add-ons: You can choose to export phrases from specific add-ons only.
4. Export: Click "Export language". Save the generated .xml, .xlf, or .csv file to your computer.

Step 3: Translate the Phrases

Open the exported file with your chosen text editor or CAT tool.

• XLIFF (.xlf) Structure:

You will only modify the <target> tags. Leave <source> and id untouched.

• XenForo XML (.xml) Structure:

For XF XML, you'll be creating new <phrase> tags with a title attribute and putting your translated text inside. This is more complex than XLIFF for a full translation from scratch. *If you used the XF XML export, it will contain only the source text. You'll need to manually add _your_language_id attributes to the phrase tags or create separate language XML files for each language during import.*

• CSV (.csv) Structure: Typically two columns: phrase_key, phrase_text. You'll add a new column for your translated text or replace the phrase_text column directly.

Important Considerations during translation:

• Placeholders: XF phrases often contain placeholders like {name}, {count}, {link}. Do not translate or modify these placeholders. They are dynamically replaced by XF. Example: "Welcome, {name}!" should become "Bienvenue, {name}!"
• HTML: Some phrases contain HTML tags (e.g., <b>, <i>, <br />). Preserve these tags exactly as they appear in the source.
• Consistency: Maintain a consistent tone and terminology throughout your translation.

Step 4: Import the Translated Phrases

Once your translation is complete, you need to import it back into your new language.

1. Go to Languages: In your Admin CP, navigate to Appearance > Languages.
2. Import Language: Click the "Import language" button.
3. Configure Import Options:
* Install from uploaded XML/XLIFF file: Browse and select your translated .xml or .xlf file.
* Target language: Crucially, select the new language you created in Step 1 (e.g., "Français (Canada)").
* Overwrite existing language: If you're updating an existing translation, check this. For a new language, it's less critical unless you're re-importing.
* Language title: Leave blank if importing into an existing language.
* Language code: Leave blank.
* Parent language: Leave blank.
4. Import: Click "Import".

Step 5: Test and Refine

1. Switch to the New Language:
* As an administrator, you can force your view to the new language using the language selector in the footer of your forum.
* Or, go to Users > Users in Admin CP, edit your own user account, and set your Language preference.
2. Browse Your Forum: Navigate through all areas of your forum (front-end, user preferences, posting, etc.) to identify untranslated phrases or areas that look off.
3. Identify Missing Phrases: If you see phrases in the parent language (e.g., English) while viewing your new language, it means they haven't been translated yet. You can then use Method 1 (Admin CP phrase editor) to translate these individual phrases, or go back to Step 2, export the "Untranslated phrases only" from your *new* language, translate them, and re-import.

This is an iterative process. You'll likely go through steps 2-5 multiple times to achieve a complete and accurate translation.

Best Practices

• Backup Regularly: Before making major changes or imports, consider backing up your XenForo database.
• Version Control: For large translation projects, consider managing your .xlf files with a version control system like Git.
• Community Contribution: If you create a full translation for a new language, consider contributing it back to the XenForo community!
• Add-on Updates: Be aware that updating XenForo or add-ons might introduce new phrases that need translation. Regularly check for untranslated phrases.
• Use CAT Tools: For professional results and efficiency, especially with XLIFF, invest time in learning a CAT tool. They offer features like translation memory, terminology management, and quality assurance checks.

By following these steps, you can effectively manage and create custom language packs for your XenForo forum, providing a more localized and engaging experience for your users.