API Translation.io Integration & Configuration

Hey folks! Let's dive into integrating Translation.io into our Laravel API backend. This guide breaks down the process, ensuring you can support multiple languages in your app. We'll cover everything from package installation to environment variable configuration, and even touch on locale middleware. Get ready to make your API multilingual!

🚀 Project Goal: Unleashing Multilingual Support

Our primary objective is to equip the Laravel API backend with multilingual capabilities using Translation.io. This involves setting up the necessary configurations and integrations, ensuring a smooth transition for users who prefer different languages. This effort is crucial for enhancing user experience and broadening the reach of your application. Let's make our app speak multiple languages!

Installation and Setup

First things first, we need to get the tio/laravel package installed via Composer. This package is our bridge to the Translation.io service. Next, we'll create the config/translation.php file and populate it with the API key from our environment variables. Make sure to add a placeholder for the TRANSLATIONIO_KEY in your .env.example file. This is crucial for new contributors to understand what's required for local development. We will also set source_locale to en (English) and target_locales to ['de'] (German). Also, configure gettext_parse_paths to include ['app', 'resources'].

Configuration of the API Key

The API key is the secret sauce that connects our application to Translation.io. We will configure the actual API key in the .env file, ensuring that it remains secure and isn't committed to the repository. This is critical for security best practices.

Locale Middleware (Optional)

The Translation.io package provides a set.locale middleware. We need to evaluate whether or not it is needed for API routes. The primary goal is to determine if adding middleware is crucial for the API routes. If the routes need language switching, then the middleware would be crucial. If not, it can be left out, as it does not affect the process of integrating and running the translation.

🛠️ Implementation Breakdown

Now, let's get into the nitty-gritty of the implementation tasks. This section provides a step-by-step approach to help you through the process.

Package Installation

composer require tio/laravel

This command installs the tio/laravel package. This package facilitates the communication between the Laravel application and the Translation.io service. Make sure that there are no errors during the installation.

Configuration File Creation

Create config/translation.php and set up the API key using your environment variables. This file houses the configuration settings for the Translation.io integration. Your .env file will hold the actual key, ensuring security.

Environment Variables

Add TRANSLATIONIO_KEY to your .env.example file and configure your actual API key in .env. This ensures that everyone working on the project understands the setup.

Locale Settings

Set source_locale to en and target_locales to ['de']. This helps define the languages that your application supports. This setup is crucial for managing the translations within the application.

Gettext Paths

Configure gettext_parse_paths to include ['app', 'resources']. This specifies the directories that will be scanned for translatable strings.

Locale Middleware (Optional)

Add Translation.io locale middleware to routes/api.php if you need to support locale switching. Evaluate the necessity of this step for your specific API endpoints.

Translation Initialization

Run php artisan translation:init to initialize the Translation.io sync. This command syncs the application's translatable strings with the Translation.io service.

Documentation and Changelog

Add Translation.io credit to README.md and update CHANGELOG.md with an entry in the [Unreleased] section.

Testing and Code Quality

Ensure all tests are passing, and that PHPStan and Pint checks are also passing. Maintain the highest level of code quality.

✅ Acceptance Criteria: Ensuring Success

Here’s a checklist to ensure everything runs smoothly.

Package and Environment

Make sure the Translation.io package is correctly installed and configured. Verify that environment variables are set up correctly, including the placeholder in .env.example and the actual key in .env. Confirm that the API key is securely stored and not visible in version control.

Command Execution and Dashboard Sync

Ensure php artisan translation:init executes successfully. Check that the Translation.io dashboard displays the project as synced.

Documentation and Testing

Verify that the README includes a mention of Translation.io, which is a requirement for the Open Source plan. Make sure all tests pass and that the codebase maintains ≥80% coverage. Ensure that PHPStan is at its maximum level and Laravel Pint is also passing.

Code Updates and Adherence

Confirm that CHANGELOG.md is updated and that there are no breaking changes to existing API endpoints. Ensure that the LOC count is ≤ 600 (excluding lock files), or that it's marked with a large-pr-approved label if necessary. These steps validate the overall success of the implementation.

🔗 Dependencies and Technical Notes

Let's break down the dependencies and technical aspects to give you a clearer picture.

Dependencies

This integration hinges on a Translation.io account setup. The front-end implementation depends on this backend work. The backend implementation needs to be ready first, and then the front end can be implemented.

Technical Details

Package: tio/laravel (https://github.com/translation/laravel)

API Key: 0ebce5906cb64a93bbd845cf7925a4ae (store in .env as TRANSLATIONIO_KEY)

Configuration File: config/translation.php

Locales: Source: en (English), Target: de (German)

Gettext Paths: ['app', 'resources'] - scans these directories for translatable strings

Middleware: Translation.io provides a set.locale middleware - evaluate if needed for API routes

Open Source Plan Requirements: Public repository (✓ already public), Mention Translation.io in README

🧪 Testing Strategy: Ensuring Robustness

Thorough testing is crucial to ensure the integration functions correctly and doesn't disrupt existing functionality. Here’s a testing strategy.

Configuration Validation

Verify that the configuration loads correctly. This step ensures that the application can read the configuration file and use the settings correctly. Proper configuration is the foundation for successful integration.

Command Execution

Test that php artisan translation:init completes without errors. The execution of this command is essential for initializing the translation process and synchronizing the translatable strings with the Translation.io service. This step validates that the command works as expected.

Functionality and Sync

Ensure no existing functionality is broken. Verify that the Translation.io dashboard receives the initial sync of strings. Confirming that the sync occurs correctly ensures that the application's translatable strings are synchronized with the Translation.io service.

Locale Switching (If Applicable)

Test locale switching (if middleware is added) to verify that language changes occur smoothly. Verify the functionality of the locale switching, ensuring users can switch between languages without encountering issues.

📝 PR Linking Instructions and Important Reminders

When creating the PR for this sub-issue, include the following in your PR description:

Fixes #<this-sub-issue-number>
Part of: #83

⚠️ Important:

Do NOT use Fixes #83 – this is not the last sub-issue. The epic should only close when the frontend implementation is also complete.

We hope this comprehensive guide has helped you! Happy coding, guys!