FEATURE REQUEST: Add support for translated error messages using gettext

[diderich]

It would be great if the error messages would be translatable through gettext, eg., _("Error message").'. '._("Language").' '.$lang.' '._("not supported").

[daniel-jones-deepl]

Hi @diderich, thanks for opening this issue. I want to understand more about this feature. Do you mean you deepl-php should pass error messages to gettext before throwing exceptions? Or that the error messages should be reworded somehow?

I also want to note that some error messages come from the DeepL API, this package only forwards those messages on.

[diderich]

My use case is as follows: I am developing an application (i.e., a server that will display photos and associated captions in the language of the end user). I want the application to display all information in the language selected by the user of the application.

The application contains two types of text to be localized:

1. Static text - Static text is known at the time of the development of the application. In my case this would be the user interface text, error messages, etc. To translate these texts, I am using the gettext API. I am i) encoding all strings using _('...'), ii) extracting the encoded strings using xgettext, iii) translating them (manually or using DeepL), and iv) making them available to the application using the gettext API.
2. Dynamic text - Dynamic text that is unknown and provided by the applocation users. In my case this would be the caption information associated with the photos. To translate these texts, I am using DeepL through the php API (with a local cache avoiding to having to re-translate the same information over and over again). This works perfectly fine.

In the case of error messages generated by third-party APIs, I am using the second method to translate them (dynamic translation). But this does not work with error messages from the DeepL API, as by reason for the error, the translation API is unavailable.

I currently see two possible approaches for showing localized DeepL API error messages to the user, that is, 1) the engineering approach, and 2) the designer approach:

Engineering approach

The DeepL API will

1. generate a unique exception per error (allowing a 1-1 relationship between error and error message) , or
2. the API will generate a unique error message identifier in the exception, rather than or in addition to, the current error message (allowing a 1-1 relationship between error identifier and error message)

These approaches would allow my (or anyone using the API) application to generate and translate whatever error message I/they want to show.

Designer approach

The DeepL will provide support for using the gettext API to translate any error message generated by enclosing the error messages using _('...'). Ths would allow me/the user to extract the error messages using xgettext, incorporate them with the other messages in the application, and handle them the same way. Pass-though error messages from the back end would also be enclosed in _('...'), so that if/when they are known they could be translated.

Parameter handling

Both approaches have one additional challenge: How to handle parameters in the error message, e.g., if the error is that the language selected is unknown, how to return the actually unknown language. For example pbin the message The language 'pb' is unknown. In the engineering approach, this could be handled by extending the Exception and adding a function getValues(): array returning an array of parameters. In the designer approach, the location of those parameters could be by using sprintf qualifiers, e.g. %s (for example writing sprintf(_('The language "%s" is unknown'), $err_lang) or by chunking the message into _('The language').' "'.$err_lang.'" '._('is unknown')

[daniel-jones-deepl]

Thank you for the very detailed explanation! I understand what you mean now.

Regarding the Engineering approach, there are some unique exceptions in this PHP library for the common error cases, for example AuthorizationException, QuotaExceededException, ConnectionException, but you are right that these do not cover all error cases; some error messages do not originate in this PHP library but instead come directly from the API. I will ask the API team about assigning error codes to each different error message.

PS: As an aside, I assume you are using the "language unknown" error messages as an example, but if not: to avoid errors about unsupported languages, you can list the available languages using getSourceLanguages and getTargetLanguages.