implement csv export/import

Author: QuentinGab

README.md

@@ -56,6 +56,12 @@ Easily manage all your Laravel translation strings with powerful features:
 1. [Detecting Dead Translations](#detecting-dead-translations)
     - [CLI Usage](#cli-usage-2)
     - [Programmatic Usage](#programmatic-usage-2)
+1. [Export to a CSV](#export-to-a-csv)
+    - [CLI Usage](#cli-usage-3)
+    - [Programmatic Usage](#programmatic-usage-3)
+1. [Import from a CSV](#import-from-a-csv)
+    - [CLI Usage](#cli-usage-4)
+    - [Programmatic Usage](#programmatic-usage-4)
 
 ## How does it work?
 
@@ -496,6 +502,50 @@ php artisan translator:dead en
 Translator::getDeadTranslations(locale: 'fr');
 ```
 
+## Export to a CSV
+
+Service: `exporter`
+
+Export all your translation strings to a CSV file in the following format:
+
+| Key                 | English | French    |
+| ------------------- | ------- | --------- |
+| messages.auth.login | Login   | Connexion |
+
+### CLI Usage
+
+```bash
+php artisan translator:export /path/to/my/file.csv
+```
+
+### Programmatic Usage
+
+```php
+$path = Translator::exportTranslations('/path/to/my/file.csv');
+```
+
+## Import from a CSV
+
+Service: `exporter`
+
+Import translation strings from a CSV file. Ensure your CSV follows the format below:
+
+| Key                 | English | French    |
+| ------------------- | ------- | --------- |
+| messages.auth.login | Login   | Connexion |
+
+### CLI Usage
+
+```bash
+php artisan translator:import /path/to/my/file.csv
+```
+
+### Programmatic Usage
+
+```php
+$translations = Translator::importTranslations('/path/to/my/file.csv');
+```
+
 ## Testing
 
 Run tests using:

composer.json

@@ -25,6 +25,7 @@
         "nikic/php-parser": "^5.1",
         "openai-php/laravel": "^0.11",
         "spatie/laravel-package-tools": "^1.16",
+        "spatie/simple-excel": "^3.7",
         "symfony/finder": "^6.0||^7.0",
         "symfony/intl": "^7.2"
     },

config/translator.php

@@ -3,6 +3,7 @@
 declare(strict_types=1);
 
 use Elegantly\Translator\Drivers\PhpDriver;
+use Elegantly\Translator\Services\Exporter\CsvExporterService;
 use Elegantly\Translator\Support\LocaleValidator;
 
 return [
@@ -175,4 +176,17 @@
 
     ],
 
+    /*
+    |--------------------------------------------------------------------------
+    | Exporter/Importer Service
+    |--------------------------------------------------------------------------
+    |
+    | These are the services that can be used to export and import your translations.
+    | You can customize their behavior here, or you can define your own service.
+    |
+    */
+    'exporter' => [
+        'service' => CsvExporterService::class,
+    ],
+
 ];

src/Commands/ExportCommand.php

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Elegantly\Translator\Commands;
+
+use Illuminate\Contracts\Console\PromptsForMissingInput;
+
+use function Laravel\Prompts\info;
+use function Laravel\Prompts\intro;
+
+/**
+ * Display translations strings found in codebase but not in a locale
+ */
+class ExportCommand extends TranslatorCommand implements PromptsForMissingInput
+{
+    public $signature = 'translator:export {path} {--driver=}';
+
+    public $description = 'Export all the translations in a file.';
+
+    public function handle(): int
+    {
+        /** @var string $path */
+        $path = $this->argument('path');
+
+        $translator = $this->getTranslator();
+
+        intro('Using driver: '.$translator->driver::class);
+
+        $translator->exportTranslations($path);
+
+        info("Translations sucessfully exported here: {$path}");
+
+        return self::SUCCESS;
+    }
+}

src/Commands/ImportCommand.php

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Elegantly\Translator\Commands;
+
+use Illuminate\Contracts\Console\PromptsForMissingInput;
+
+use function Laravel\Prompts\info;
+use function Laravel\Prompts\intro;
+
+/**
+ * Display translations strings found in codebase but not in a locale
+ */
+class ImportCommand extends TranslatorCommand implements PromptsForMissingInput
+{
+    public $signature = 'translator:import {path} {--driver=}';
+
+    public $description = 'Import all the translations from a file.';
+
+    public function handle(): int
+    {
+        /** @var string $path */
+        $path = $this->argument('path');
+
+        $translator = $this->getTranslator();
+
+        intro('Using driver: '.$translator->driver::class);
+
+        $imported = $translator->importTranslations($path);
+
+        info('Translations sucessfully imported.');
+
+        return self::SUCCESS;
+    }
+}

src/Exceptions/TranslatorServiceException.php

@@ -22,4 +22,9 @@ public static function missingSearchcodeService(): self
     {
         return new self('The searchcode service is missing. Please define a searchcode service in configs.');
     }
+
+    public static function missingExporterService(): self
+    {
+        return new self('The exporter service is missing. Please define an exporter service in configs.');
+    }
 }

src/Facades/Translator.php

@@ -6,6 +6,7 @@
 
 use Elegantly\Translator\Collections\Translations;
 use Elegantly\Translator\Drivers\Driver;
+use Elegantly\Translator\Services\Exporter\ExporterInterface;
 use Illuminate\Support\Facades\Facade;
 
 /**
@@ -21,6 +22,8 @@
  * @method static Translations deleteTranslations(string $locale, array<int, string> $keys)
  * @method static Translations sortTranslations(string $locale)
  * @method static Translations saveTranslations(string $locale, Translations $translations)
+ * @method static string exportTranslations(string $path, ?ExporterInterface $exporter = null)
+ * @method static array<string, array<int|string, scalar>> importTranslations(string $path, ?ExporterInterface $exporter = null)
  * @method static void clearCache()
  *
  * @see \Elegantly\Translator\Translator

src/Services/Exporter/CsvExporterService.php

@@ -0,0 +1,80 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Elegantly\Translator\Services\Exporter;
+
+use Illuminate\Support\Arr;
+use Spatie\SimpleExcel\SimpleExcelReader;
+use Spatie\SimpleExcel\SimpleExcelWriter;
+
+class CsvExporterService implements ExporterInterface
+{
+    public function __construct()
+    {
+        //
+    }
+
+    public static function make(): self
+    {
+        return new self;
+    }
+
+    public function export(array $translationsByLocale, string $path): string
+    {
+
+        $writer = SimpleExcelWriter::create($path);
+
+        /** @var string[] $locales */
+        $locales = array_keys($translationsByLocale);
+
+        $writer->addHeader(['key', ...$locales]);
+
+        /** @var string[] $keys */
+        $keys = collect($translationsByLocale)
+            ->flatMap(fn ($translations) => $translations->keys())
+            ->unique()
+            ->all();
+
+        foreach ($keys as $key) {
+            $writer->addRow([
+                'key' => $key,
+                ...array_map(fn ($locale) => $translationsByLocale[$locale]->get($key), $locales),
+            ]);
+        }
+
+        $writer->close();
+
+        return $path;
+
+    }
+
+    public function import(string $path): array
+    {
+
+        /**
+         * @var array<string, array<string, scalar>> $translationsByLocale
+         */
+        $translationsByLocale = [];
+
+        $rows = SimpleExcelReader::create($path)->getRows();
+
+        foreach ($rows as $row) {
+
+            $key = Arr::pull($row, 'key');
+
+            foreach ($row as $locale => $value) {
+
+                $translationsByLocale[$locale] = [
+                    ...($translationsByLocale[$locale] ?? []),
+                    $key => $value,
+                ];
+
+            }
+
+        }
+
+        return $translationsByLocale;
+
+    }
+}

src/Services/Exporter/ExporterInterface.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Elegantly\Translator\Services\Exporter;
+
+use Elegantly\Translator\Collections\Translations;
+
+interface ExporterInterface
+{
+    public static function make(): self;
+
+    /**
+     * @param  array<string, Translations>  $translationsByLocale
+     */
+    public function export(array $translationsByLocale, string $path): string;
+
+    /**
+     * @return array<string, array<string, scalar>>
+     */
+    public function import(string $path): array;
+}

src/Translator.php

@@ -8,6 +8,7 @@
 use Elegantly\Translator\Collections\Translations;
 use Elegantly\Translator\Drivers\Driver;
 use Elegantly\Translator\Exceptions\TranslatorServiceException;
+use Elegantly\Translator\Services\Exporter\ExporterInterface;
 use Elegantly\Translator\Services\Proofread\ProofreadServiceInterface;
 use Elegantly\Translator\Services\SearchCode\SearchCodeServiceInterface;
 use Elegantly\Translator\Services\Translate\TranslateServiceInterface;
@@ -19,6 +20,7 @@ final public function __construct(
         public ?TranslateServiceInterface $translateService = null,
         public ?ProofreadServiceInterface $proofreadService = null,
         public ?SearchCodeServiceInterface $searchcodeService = null,
+        public ?ExporterInterface $exporter = null,
     ) {
         //
     }
@@ -29,7 +31,8 @@ public function driver(null|string|Driver $name): static
             driver: $name instanceof Driver ? $name : TranslatorServiceProvider::getDriverFromConfig($name),
             translateService: $this->translateService,
             proofreadService: $this->proofreadService,
-            searchcodeService: $this->searchcodeService
+            searchcodeService: $this->searchcodeService,
+            exporter: $this->exporter,
         );
     }
 
@@ -327,6 +330,56 @@ public function saveTranslations(
 
     }
 
+    public function exportTranslations(
+        string $path,
+        ?ExporterInterface $exporter = null
+    ): string {
+        $exporter = $exporter ?? $this->exporter;
+
+        if (! $exporter) {
+            throw TranslatorServiceException::missingExporterService();
+        }
+
+        $locales = $this->getLocales();
+
+        $translationsByLocale = collect($locales)
+            ->mapWithKeys(fn ($locale) => [$locale => $this->getTranslations($locale)])
+            ->all();
+
+        return $exporter->export($translationsByLocale, $path);
+
+    }
+
+    /**
+     * @return array<string, array<int|string, scalar>>
+     */
+    public function importTranslations(
+        string $path,
+        ?ExporterInterface $exporter = null
+    ): array {
+        $exporter = $exporter ?? $this->exporter;
+
+        if (! $exporter) {
+            throw TranslatorServiceException::missingExporterService();
+        }
+
+        $translationsByLocale = $exporter->import($path);
+
+        foreach ($translationsByLocale as $locale => $values) {
+
+            $this->transformTranslations(
+                locale: $locale,
+                callback: function ($translations) use ($values) {
+                    return $translations->merge($values);
+                },
+                sort: config()->boolean('translator.sort_keys'),
+            );
+
+        }
+
+        return $translationsByLocale;
+    }
+
     public function clearCache(): void
     {
         $this->searchcodeService?->getCache()?->flush();