README.md

Namespace Translator

Translations manager for Nette framework using contributte/translation. It allows you to have your translation files located where they are really used (e.g. next to a component or a model).

No more global translations mess! 💪

Installation

Via Composer

composer require wavevision/namespace-translator

Note: This will automatically install contributte/translation too.

Usage

Register required extensions in your project config:

extensions:
	translation: Contributte\Translation\DI\TranslationExtension
	namespaceTranslator: Wavevision\NamespaceTranslator\DI\Extension

You can configure namespaceTranslator as follows (default values):

namespaceTranslator:
    dirNames: # names of dirs in which namespace translations will reside
        - translations
        - Translations
    loaders: # namespace translations loaders
        neon: Wavevision\NamespaceTranslator\Loaders\Neon
        php: Wavevision\NamespaceTranslator\Loaders\TranslationClass
        flatJson: Wavevision\NamespaceTranslator\Loaders\FlatJson

Note: Refer to Contributte docs for further info about configuring translation.

With this setup, you can start managing your translations like a boss 🤵.

The best thing is the translator keeps full backwards compatibility with contributte/translation setup, so you can still use your translations as you are used to and migrate to namespaces step-by-step. Any translation not found by namespace translator will fallback to translation resources.

Translated components

Your components (or presenters) can use Wavevision\NamespaceTranslator\TranslatedComponent trait.

Make sure your component has inject allowed.

The trait will provide your component class / template with $translator property / variable. The translator will look for resources in configured dir names inside component's namespace.

Note: The translate macro in component templates will, of course, work too.

Translated models

Even your services can use the translator. Simply use Wavevision\NamespaceTranslator\NamespaceTranslator.

Make sure your service is registered with inject: true in your config.

After that, it works the same as with your components.

Loaders

There are three resource loaders included by default:

• Neon – loads translations from neon files
• TranslationClass – loads translations from PHP classes
• FlatJson - loads translations from flat (no nesting) json files

Using PHP classes is useful when you want to refer to your translations using constants so changes in your resources get propagated throughout the whole project.

Classes containing translations must implement Wavevision\NamespaceTranslator\Resources\Translation.

You can also create and register your own loader, just make sure it implements Wavevision\NamespaceTranslator\Loaders\Loader.

Export \ Import

For exporting \ importing translations to \ from CSV or GoogleSheet (or both) update configuration file

namespaceTranslator:
	transfer:
		google:
			credentials: credentials.json
			sheetId: googleSheetId
			parts:
				- directory: %vendorDir%/../App/AdminModule
				  tabName: admin-module
		csv:
			parts:
				- directory: %vendorDir%/../App/FrontModule
				  filename: %vendorDir%/../temp/front-module.csv

Set locales whitelist from contributte/translation. Whitelist is used for creating translation columns in export.

Run command to export translations

php {bin/console} namespace-translator:export

Update translations, then run command to import them

php {bin/console} namespace-translator:import

Google Sheet

For accessing Google sheet you will need server-to-server API key and sheet ID.

Export example

From files

# file translations/en.neon
hello: Hello %name%

# file translations/de.neon
hello: Hallo %name%

<?php declare(strict_types=1); //file Translations/Cs.php

use Wavevision\NamespaceTranslator\Resources\Translation;
use Wavevision\NamespaceTranslator\Loaders\TranslationClass\Message;

class Cs implements Translation
{
    public const HELLO = 'hello';

    public const NAME = 'name';

    public static function define() : array
    {
        return [self::HELLO => Message::create('Hello %s', self::NAME)]; 
    }
}

export should look like this

file,           key,          en,                  de,                  format
/translations/, hello,        Hello %name%,        Hallo %name%,        neon
/Translations/, c:self-HELLO, Hello {c:self-Name}, ,                    php

columns file, key and format shouldn't be modified.

For details see example export.csv.

Limitation of TranslationClass

• Define function must have only one statement (return [...])
• Array keys must be strings or class constants
• Array values must be arrays, strings or Message::create() function calls
• Php files should be linted after import

Examples

See tests for example app implementation.