feat: Support for localized strings #120

dimtrovich · 2024-11-29T19:25:45Z

Introduction of translation support.
Until now, all the texts generated by the CLI have been in English. The problem is that some people run commands in other languages (French in my case) and so you get a mixture of English and French, which isn't very cool to see.

This subject has already been discussed here #64

With this PR, the texts are translated and the developer can therefore use the language best suited to his project

// example

<?php

use Ahc\Cli\Application;
use Ahc\Cli\Translations\Translator;

include './vendor/autoload.php';

Translator::$locale = 'ru';  // en, fr, es, de, ru 
$app = new Application('My Application');

$app->command('rmdir');

$app->handle($_SERVER['argv']);

en (default)

fr - French

es - Spanish

de - German

ru - Russian

adhocore

hello @dimtrovich thank you. it definitely is a big and significant work so kudos to that.

however i feel like we shouldn't have it in the library as it is quite niche and a bit away from focus of cli package.
instead can we make it as a plugin (which you can put under your git repo and we can link it up in readme here with instructions for i18n)

adhocore · 2024-12-01T01:32:08Z

cc @kodie what's your thoughts on it? for me it is big feature &/or change surface to be in the core

dimtrovich · 2024-12-01T08:37:01Z

Hello @adhocore. Sorry for the delay.
The idea of a plugin is a good one, but at the moment the package doesn't offer any mechanism for creating extensions. This idea could be implemented in v2!!!

The other problem I have with this is that it will be quite difficult to capture your hard-coded text and then translate it... There's a bit of text in all the classes and also between the special formatting tags (for example, in the error stack display method, like <red>Thrown In<end/>:).

With this, I think it will be impossible to externalize the translation system. On the other hand, you could remove the translation files and leave just English, and the developer who wants a different language could extend it as I mentioned in the Readme.

adhocore · 2024-12-01T13:00:22Z

right now there is no way to externalize translation because thats not the focus/usecase of this pkg.

as for this pr, the surface of code change is too big for not necessarily must have feature.

i would like to have it bare minimum like so:

namespace Ahc\Cli;

class Application
{
  public static $locale = 'en';
  public static $locales = [];

  public static function addLocale(string $loc, array $texts, bool $default)
  {
    if ($default) Application::$locale = $loc;
    Application::$locales[$loc] = $texts;
  }
}

function t(string $text, array $args): string
{
  $loc = Application::$locale;
  // EN is already there as original text (no keys needed)
  $txt = Application::$locales[$loc][$txt] ?? $txt;
 
  return sprintf($txt, ...$args);
}

// internally cli pkg uses t(). 
// eg: in https://github.com/adhocore/php-cli/blob/main/src/Input/Command.php#L199
//  throw new InvalidParameterException('Only last argument can be variadic');
// will be
//  throw new InvalidParameterException(t('Only last argument can be variadic'));

externally end users would use it like so:

Application::addLocale('fr', [
  'Only last argument can be variadic' => 'Seul le dernier argument peut être variadique',
], true);

now since there is no translation key in code, we just list them in the readme from:

https://github.com/adhocore/php-cli/blob/b8e089f464a647b0ec43682a3fd2f2a7dba1a81a/src/Translations/en.php

adhocore · 2024-12-01T13:11:29Z

also the sprintf positional arguments needs to be handled as explained here: https://www.php.net/manual/en/function.sprintf.php#refsect1-function.sprintf-examples

example text: 'The current (%d) is greater than the total (%d).'

kodie · 2024-12-01T16:00:45Z

I do like the compromise of allowing string translation, but not having the cli package need to maintain the different translations. What @adhocore suggests makes translations work similar to how the styles system works now which is nice. There are built in defaults, but everything can be customized. My one slight update to what @adhocore suggested would be to make it possible to customize the built-in local as well. For example if I would like the "Show help" description on the --help option to say something like "Shows helpful information about a command". I like this because after all the recent updates, I think this might be the one last thing that currently can't be customized.

dimtrovich · 2024-12-02T09:18:11Z

right now there is no way to externalize translation because thats not the focus/usecase of this pkg.

as for this pr, the surface of code change is too big for not necessarily must have feature.

i would like to have it bare minimum like so:
namespace Ahc\Cli;

class Application
{
  public static $locale = 'en';
  public static $locales = [];

  public static function addLocale(string $loc, array $texts, bool $default)
  {
    if ($default) Application::$locale = $loc;
    Application::$locales[$loc] = $texts;
  }
}

function t(string $text, array $args): string
{
  $loc = Application::$locale;
  // EN is already there as original text (no keys needed)
  $txt = Application::$locales[$loc][$txt] ?? $txt;
 
  return sprintf($txt, ...$args);
}

// internally cli pkg uses t(). 
// eg: in https://github.com/adhocore/php-cli/blob/main/src/Input/Command.php#L199
//  throw new InvalidParameterException('Only last argument can be variadic');
// will be
//  throw new InvalidParameterException(t('Only last argument can be variadic'));
externally end users would use it like so:
Application::addLocale('fr', [
  'Only last argument can be variadic' => 'Seul le dernier argument peut être variadique',
], true);
now since there is no translation key in code, we just list them in the readme from:

https://github.com/adhocore/php-cli/blob/b8e089f464a647b0ec43682a3fd2f2a7dba1a81a/src/Translations/en.php

It's true that I'm not a big fan of having free-to-air channels as table keys. However, I like it because at least it means that all the text is directly readable internally.
I'll do an update soon.

dimtrovich · 2024-12-02T09:21:57Z

@adhocore which means that we'll have to remove the embedded translations from the package and leave it up to the developer.

adhocore · 2024-12-02T12:10:42Z

yes we have to remove and thats what makes this change less disruptive and all-compatible

and no, it's not the only translation system that uses real en texts as keys (https://www.hiddentechies.com/blog/magento-2/magento2-generate-language-translation-csv/)

kodie · 2024-12-02T12:44:21Z

WordPress also works that way: https://developer.wordpress.org/reference/functions/__/

kodie · 2024-12-02T14:11:40Z

Just an idea too, once it's all set up, translations could be stored in gists much like I did with colors: https://gist.github.com/kodie/b63881ccf4368e9e00c0c3277779524a that way the tool can still be translated without having to do it manually every time.

dimtrovich · 2024-12-02T18:57:54Z

yes we have to remove and thats what makes this change less disruptive and all-compatible

done

dimtrovich · 2024-12-02T19:02:23Z

Just an idea too, once it's all set up, translations could be stored in gists much like I did with colors: https://gist.github.com/kodie/b63881ccf4368e9e00c0c3277779524a that way the tool can still be translated without having to do it manually every time.

done. https://gist.github.com/dimtrovich/1597c16d5c74334e68eef15a4e7ba3fd

however, it looks like you didn't put it in the doc. it might as well be in the doc so we don't have to look too hard.
if you hadn't mentioned it here I'd never have known about it, even though it's a real goldmine.

adhocore · 2024-12-03T01:56:00Z

src/Helper/InflectsString.php

+    /**
+     * Translates a message using the translator.
+     */
+    public static function translate(string $text, array $args = []): string


~~it could be a simple function t() or __() under namespace Ahc\cli (not method) :)~~

~~then can be imported as use function Ahc\Cli\t~~

oh ok but i had ~~striked~~ this one and left another note 😀

I don't quite understand. Can you please explain?
the function t() simple or a method in the InflectsString trait. because now I don't understand.

#120 (comment)

OK, now I understand better. I hadn't paid attention to the link you provided. I'm going to manage the argument positioning

So, in the case of the t() function, should we leave it or go back to the previous translate method?

its ok as it is, we just need to consider the sprintf for wrapping up

In this case, shouldn't positioning only be managed for texts with more than one argument?

For example, this is relevant for The current (%d) is greater than the total (%d). but much less so for Command %s not found.

I would like to leave Command %s not found unchanged but change The current (%d) is greater than the total (%d). to The current (%1$d) is greater than the total (%2$d)..

or we'll make everything the same

ya thats fine

done

gist sample was also updated

adhocore

for now no need to have t() but the positional sprintf must be handled :)

dimtrovich · 2024-12-03T11:42:10Z

positional sprintf must be handled :)

how? I think this has already been taken into account. 🤔🤔

kodie · 2024-12-03T13:44:18Z

Just an idea too, once it's all set up, translations could be stored in gists much like I did with colors: https://gist.github.com/kodie/b63881ccf4368e9e00c0c3277779524a that way the tool can still be translated without having to do it manually every time.

done. https://gist.github.com/dimtrovich/1597c16d5c74334e68eef15a4e7ba3fd

however, it looks like you didn't put it in the doc. it might as well be in the doc so we don't have to look too hard. if you hadn't mentioned it here I'd never have known about it, even though it's a real goldmine.

Putting it in the readme is a good idea! I came up with it after the PR was merged in

see https://www.php.net/manual/en/function.sprintf.php#refsect1-function.sprintf-examples

dimtrovich added 5 commits November 29, 2024 17:23

feat: add support for localized strings

26a7f14

test: write tests for translation manager

a5d6313

patch: add a missing translation key

dae519b

provides fr, es, de and ru translations

733285e

docs: documentation for i18n support

b8e089f

adhocore reviewed Nov 30, 2024

View reviewed changes

dimtrovich added 5 commits December 2, 2024 18:34

refactor: using plain text instead of keys for translations

2f187bd

refactor: deletion of the Translator as it is no longer in use

16f8b48

test: app translate

c8dce0e

docs: update documentation of i18n support

a0845f6

Merge branch 'main' into translations

3bd4243

adhocore reviewed Dec 3, 2024

View reviewed changes

patch: use simple function t() instead method translate

9b6f42f

patch: manage argrument positioning of sprintf in translation

be819d4

see https://www.php.net/manual/en/function.sprintf.php#refsect1-function.sprintf-examples

adhocore approved these changes Dec 4, 2024

View reviewed changes

adhocore merged commit 86be16e into adhocore:main Dec 4, 2024
5 of 6 checks passed

adhocore mentioned this pull request Dec 4, 2024

Add support for localized strings #64

Closed

dimtrovich deleted the translations branch December 4, 2024 08:25

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: Support for localized strings #120

feat: Support for localized strings #120

dimtrovich commented Nov 29, 2024 •

edited

Loading

adhocore left a comment

adhocore commented Dec 1, 2024

dimtrovich commented Dec 1, 2024

adhocore commented Dec 1, 2024

adhocore commented Dec 1, 2024 •

edited

Loading

kodie commented Dec 1, 2024

dimtrovich commented Dec 2, 2024

dimtrovich commented Dec 2, 2024

adhocore commented Dec 2, 2024

kodie commented Dec 2, 2024

kodie commented Dec 2, 2024

dimtrovich commented Dec 2, 2024

dimtrovich commented Dec 2, 2024

adhocore Dec 3, 2024 •

edited

Loading

dimtrovich Dec 3, 2024

adhocore Dec 3, 2024

dimtrovich Dec 3, 2024 •

edited

Loading

adhocore Dec 3, 2024

dimtrovich Dec 3, 2024

adhocore Dec 3, 2024

dimtrovich Dec 3, 2024 •

edited

Loading

adhocore Dec 3, 2024

dimtrovich Dec 3, 2024 •

edited

Loading

adhocore left a comment

dimtrovich commented Dec 3, 2024

kodie commented Dec 3, 2024

feat: Support for localized strings #120

feat: Support for localized strings #120

Conversation

dimtrovich commented Nov 29, 2024 • edited Loading

adhocore left a comment

Choose a reason for hiding this comment

adhocore commented Dec 1, 2024

dimtrovich commented Dec 1, 2024

adhocore commented Dec 1, 2024

adhocore commented Dec 1, 2024 • edited Loading

kodie commented Dec 1, 2024

dimtrovich commented Dec 2, 2024

dimtrovich commented Dec 2, 2024

adhocore commented Dec 2, 2024

kodie commented Dec 2, 2024

kodie commented Dec 2, 2024

dimtrovich commented Dec 2, 2024

dimtrovich commented Dec 2, 2024

adhocore Dec 3, 2024 • edited Loading

Choose a reason for hiding this comment

dimtrovich Dec 3, 2024

Choose a reason for hiding this comment

adhocore Dec 3, 2024

Choose a reason for hiding this comment

dimtrovich Dec 3, 2024 • edited Loading

Choose a reason for hiding this comment

adhocore Dec 3, 2024

Choose a reason for hiding this comment

dimtrovich Dec 3, 2024

Choose a reason for hiding this comment

adhocore Dec 3, 2024

Choose a reason for hiding this comment

dimtrovich Dec 3, 2024 • edited Loading

Choose a reason for hiding this comment

adhocore Dec 3, 2024

Choose a reason for hiding this comment

dimtrovich Dec 3, 2024 • edited Loading

Choose a reason for hiding this comment

adhocore left a comment

Choose a reason for hiding this comment

dimtrovich commented Dec 3, 2024

kodie commented Dec 3, 2024

dimtrovich commented Nov 29, 2024 •

edited

Loading

adhocore commented Dec 1, 2024 •

edited

Loading

adhocore Dec 3, 2024 •

edited

Loading

dimtrovich Dec 3, 2024 •

edited

Loading

dimtrovich Dec 3, 2024 •

edited

Loading

dimtrovich Dec 3, 2024 •

edited

Loading