Lingo.dev CLI: Unreal Engine Integration Guide

by SLV Team 47 views
Lingo.dev CLI: Integrate Unreal Engine for Multilingual Apps

Hey folks! Ready to dive into making your Unreal Engine games multilingual using Lingo.dev CLI? This guide is your complete, step-by-step tutorial to get you from zero to a fully localized game. We'll walk through everything, so you can easily translate your game's text and create a global gaming experience. Let's get started!

What is Lingo.dev CLI?

First off, what is Lingo.dev CLI? Think of it as your best friend for handling translations. It's a command-line interface that simplifies the process of managing and implementing multilingual support in your applications. Instead of wrestling with complex translation workflows, Lingo.dev CLI lets you focus on creating awesome games. It helps you extract text, manage translations, and integrate them back into your project seamlessly. It's like having a translation wizard at your fingertips, making the whole process much smoother.

Why Use Lingo.dev CLI with Unreal Engine?

Unreal Engine is a powerhouse, but handling localization can be a bit of a headache. That's where Lingo.dev CLI comes in. Here’s why it's a game-changer:

  • Efficiency: Automates the extraction and import of text, saving you tons of time.
  • Accuracy: Reduces errors by streamlining the translation process.
  • Easy Updates: Quickly update translations and redeploy them.
  • Simplified Workflow: Integrates smoothly with your existing Unreal Engine project.
  • Team Collaboration: Makes it easier for teams to work together on localization.

Basically, it takes the pain out of making your Unreal Engine game accessible to players worldwide. Ready to make your game global? Let's go!

Prerequisites

Before we jump in, let's make sure you have everything you need. You'll need:

  • Unreal Engine: Any recent version of Unreal Engine will work. Make sure you have it installed and ready to go.
  • A Lingo.dev Account: You'll need to sign up for a Lingo.dev account. You can do this at https://lingo.dev. Don't worry, the signup is quick and easy!
  • Node.js and npm: Make sure you have Node.js and npm (Node Package Manager) installed on your system. You'll need these to install the Lingo.dev CLI. Check your installation by running node -v and npm -v in your terminal.
  • Basic Unreal Engine Knowledge: Familiarity with the Unreal Engine editor, especially with creating text and UI elements, will be helpful.
  • A Text Editor: Any text editor or IDE will work. We recommend VSCode, but use whatever you're comfortable with.

Got all that? Awesome! Let's get to the fun part.

Setting Up Your Unreal Engine Project

Alright, let's get your Unreal Engine project ready for localization. We'll cover everything from project setup to setting up basic text elements in the editor. This section is all about getting your project ready to work with Lingo.dev CLI. If you already have a project, feel free to use it. If not, don’t worry, creating a new project is easy as pie.

Creating a New Project or Opening an Existing One

  1. Launch Unreal Engine: Open the Unreal Engine editor.
  2. Create a New Project: Click on "Create Project" and select a project template. We recommend starting with a "Blank" or "Third Person" template to keep things simple. Click "Create" to start.
  3. Or Open Existing Project: If you have an existing project, open it from the project browser.

Setting Up Localization Dashboard

Unreal Engine has a built-in localization dashboard, which is your go-to for managing translations. Here’s how to set it up:

  1. Open the Localization Dashboard: Go to "Window" > "Developer Tools" > "Localization Dashboard."
  2. Add Cultures: In the dashboard, you will add the languages you want to support. For example, add "English" (en) and "French" (fr). Click the "Add" button to add each language. Unreal Engine will automatically set up the structure.
  3. Gather Text: In the dashboard, click "Gather Text." This process will identify all the text in your project that needs translation. Unreal Engine will scan all your assets and code for text strings. This is where your game starts to become multilingual!
  4. Export Text: Once the text is gathered, click "Export" to create a .csv file. This file contains all the text that needs to be translated. This is the file we'll work with using Lingo.dev CLI.

Adding Text in Your Project

To make things easier, add some sample text to your project. This will help us test the localization process later.

  1. Create a Widget: Add a new user interface widget (e.g., a simple text block). Go to "User Interface" > "Widget Blueprint" and create one. Give it a name like "MainMenuWidget."
  2. Add a Text Block: Drag a text block from the palette onto the canvas of your widget.
  3. Set the Text: In the details panel, locate the "Text" property and enter some text, like "Hello, World!" or "Welcome to the Game!".
  4. Bind the Text (Important): In the details panel, click on the "Text" property and select "Create Binding." This creates a function in the event graph that will automatically update the text. We will use this in conjunction with Lingo.dev CLI.
  5. Add to Level: Add the widget to your level so you can see it in your game.

That’s it! Your project is set up and ready to accept translations. Next, we will install and configure Lingo.dev CLI.

Installing Lingo.dev CLI

Now, let’s get the Lingo.dev CLI installed. This is where the magic starts happening! We'll use npm to install the CLI globally so you can access it from anywhere in your terminal.

Using npm to Install the CLI

  1. Open Your Terminal: Open your terminal or command prompt. Make sure you have Node.js and npm installed.

  2. Install Lingo.dev CLI: Run the following command to install the Lingo.dev CLI globally:

    npm install -g @lingodev/cli

    This command tells npm to download and install the Lingo.dev CLI package from the npm registry. The -g flag means it will install it globally, so you can use it in any project.

  3. Verify Installation: To make sure everything went smoothly, run:

    lingo --version

    If the CLI is installed correctly, you’ll see the version number printed in your terminal. If you get an error, double-check that Node.js and npm are installed correctly and try again.

Configuring the CLI

Before you start using the CLI, you need to configure it with your Lingo.dev account details. This tells the CLI how to connect to your account and manage your projects.

  1. Login: Open your terminal and run the following command to log in to your Lingo.dev account:

    lingo login

    The CLI will prompt you to enter your email and password associated with your Lingo.dev account.

  2. Initialize Lingo.dev in your Unreal Engine project: Navigate to your project directory in the terminal, then run the init command to set up the Lingo configuration files:

    lingo init

    This command creates a .lingo folder in your project directory containing the lingo.config.json file. This is the project-specific configuration file. We'll edit this file in the next step.

  3. Configure Your Project: Now, you need to configure the lingo.config.json file. This file tells the Lingo.dev CLI where to find your source language file, where to output translated files, and other important settings.

    • Open lingo.config.json in your text editor.
    • source: Set this to the path of your English .csv file that Unreal Engine exported from the Localization Dashboard.
    • target: Set this to the directory where you want the translated files to be outputted.
    • project_id: Get your project ID from the Lingo.dev dashboard. Create a project in the dashboard if you haven't already and copy your project ID.

    Here's an example of what your lingo.config.json might look like:

    {
  "source": "/Content/Localization/Game/en.csv",
  "target": "/Content/Localization/Game",
  "project_id": "your-lingodev-project-id"
}

    Make sure to adjust the paths and project ID according to your project structure. Save the file after making your changes.

Using Lingo.dev CLI with Unreal Engine

Now that everything is set up, let's see Lingo.dev CLI in action with your Unreal Engine project. We'll go through the key commands you'll use to extract text, translate it, and import the translations back into your game.

Extracting Text

This step involves using the Localization Dashboard in the Unreal Engine and exporting the CSV file. Then, configure the source file in your lingo.config.json file.

Translating Your Text

  1. Upload Your Source File to Lingo.dev: The CLI makes uploading simple.

    lingo push

    This command uploads your source language file (the one containing the text to be translated) to your project in Lingo.dev. The CLI will upload your CSV file to your Lingo.dev project.

  2. Translate Your Strings: Log in to your Lingo.dev dashboard. You will see the untranslated strings. Either manually translate these strings or use the translation services provided by Lingo.dev. This is where the magic of Lingo.dev shines! You can use machine translations or hire professional translators directly from the dashboard.

Importing Translations

Once the translations are complete, you'll need to download them and import them into your Unreal Engine project.

  1. Pull Translations: Use the pull command to download the translations.

    lingo pull

    This command downloads all the translations from Lingo.dev and saves them in your target directory that you configured in lingo.config.json. You should now have translated CSV files in your target directory. For instance, you will see a CSV file for each language supported.

  2. Import Translations into Unreal Engine: Open the Localization Dashboard in Unreal Engine. Click the "Import" button and select the new translated .csv files. Unreal Engine will now update your text resources with the translations. The import process will automatically update the text in your project.

Testing Your Localized Game

Testing is crucial to ensure that everything works as expected. Here’s how you can test your localized game in Unreal Engine.

Changing the Game Language

  1. In the Unreal Editor: In the Unreal Engine editor, you can change the game language in the project settings or through the console commands (see below). This is the simplest and most direct method for testing.

    • Open your project settings and navigate to "Project Settings" > "Localization." You can set the "Default Culture" and also test the localized versions by switching the culture.

  2. Using Console Commands: You can use console commands to change the game's language at runtime.

    • Open the console in-game (usually by pressing the ";" or "~") and type the following command to set the culture (replace "fr" with the language code):

      culture fr

    • This command will instantly change the game's language to French (if you have translations for it). You can use this for any language you have translations for.

Verifying Text Display

  1. Check UI Elements: Go back to your UI widgets (like the main menu widget we created earlier) and make sure the text you translated is displayed correctly.
  2. Test All Text: Go through all the text elements in your game, including in-game messages, dialogue, and UI elements. Ensure that everything is translated and displayed as expected.
  3. Look for Issues: Check for any layout issues, text clipping, or incorrect characters. Correct these issues if any occur by adjusting text properties in Unreal Engine or re-translating the text.

Advanced Features and Tips

Let's get a little fancy and look at some advanced features and tips to level up your localization game!

Handling Dynamic Text

Sometimes, your text isn't static; it needs to change based on the game's state or player actions. No worries, Lingo.dev CLI and Unreal Engine have got you covered!

  1. Using Variables: Use variables in your text strings within Unreal Engine. This way, you can easily change values at runtime.
  2. Formatting Text: Take advantage of Unreal Engine's text formatting options, like the "Format Text" node in Blueprints, to handle variables in your text.
  3. Update Your Localization Files: Make sure to update your localization files whenever you add new dynamic text.

Continuous Integration (CI/CD)

Want to automate your localization process? You can integrate Lingo.dev CLI into your CI/CD pipeline! This means you can automatically extract text, upload it, download translations, and import them into your game with every build. Pretty cool, right?

  1. Automate with Scripts: Write scripts to automate the lingo push, lingo pull, and Unreal Engine import steps.
  2. Integrate with Build Systems: Integrate these scripts into your build system, like Jenkins or GitLab CI, so that localization updates happen automatically.

Best Practices

Follow these tips to make your localization process as smooth as possible:

  • Plan Ahead: Always plan for localization early in your project to save time and effort later.
  • Use Consistent Text Keys: Ensure your text keys are consistent throughout your project.
  • Test Thoroughly: Test your localized game in different languages and on different devices.
  • Involve Translators: Get professional translators involved to ensure high-quality translations.

Troubleshooting

Encountering issues? Don't sweat it! Here are some common problems and their solutions:

  • CLI Not Found: If you get an error that the lingo command isn't found, double-check that you've installed the CLI correctly (using npm install -g @lingodev/cli). Make sure your PATH environment variable includes the npm global packages directory.
  • Incorrect Paths: If translations aren't showing up, double-check the file paths in your lingo.config.json file. Ensure the paths to your source and target files are correct.
  • Missing Translations: If some text is missing, make sure that the text is included in your source CSV file and that it has been translated in the Lingo.dev dashboard.
  • Character Encoding Issues: If you are encountering special characters that are not displaying correctly, make sure you are using UTF-8 encoding in your CSV files. Also, check for encoding issues in your editor and the Unreal Engine project settings.
  • Check the Console: Always check the console in your terminal and the Unreal Engine Output Log for any error messages. They will provide clues on what is going wrong.

If you're still stuck, check out the Lingo.dev documentation or reach out to their support team for help.

Conclusion

And there you have it, folks! You've successfully integrated Lingo.dev CLI into your Unreal Engine project. You're now equipped to make your game multilingual and reach a global audience. Keep experimenting, keep learning, and most importantly, keep creating! Happy translating, and have fun building your multilingual game! With Lingo.dev CLI, you're well on your way to global domination in the gaming world.