Translations

.github/workflows/ci.yaml

@@ -102,15 +102,24 @@ jobs:
       matrix:
         operating-system: [ "ubuntu-latest", "macos-latest", "windows-latest" ]
         php-version: [ "7.4", "8.0", "8.1" ]
+        php-extensions: [ "fileinfo, intl, json, mbstring, sodium, ssh2" ]
         composer-flags: [ "" ]
         experimental: [ false ]
         include:
           - operating-system: "ubuntu-latest"
             php-version: "7.4"
+            php-extensions: "fileinfo, intl, json, mbstring, sodium, ssh2"
             composer-flags: "--prefer-lowest --prefer-stable"
             experimental: false
           - operating-system: "ubuntu-latest"
             php-version: "8.2"
+            php-extensions: "fileinfo, intl, json, mbstring, sodium, ssh2"
+            composer-flags: "--ignore-platform-req=php+"
+            experimental: false
+          # No intl
+          - operating-system: "ubuntu-latest"
+            php-version: "8.2"
+            php-extensions: "fileinfo, json, mbstring, sodium, ssh2"
             composer-flags: "--ignore-platform-req=php+"
             experimental: false
 
@@ -124,6 +133,7 @@ jobs:
           version: "${{ matrix.php-version }}"
           coverage: "pcov"
           token: "${{ secrets.GITHUB_TOKEN }}"
+          extensions: "${{ matrix.php-extensions }}"
 
       - name: "Composer"
         uses: "orisai/github-workflows/.github/actions/setup-composer@v1"

Makefile

@@ -30,6 +30,9 @@ phpstan-baseline: ## Add PHPStan errors to baseline
 
 # Tests
 
+update-snapshots: ## Update snapshots used for testing
+	$(PRE_PHP) php tests/Snapshots/update-snapshots.php
+
 .PHONY: tests
 tests: ## Run all tests
 	$(PRE_PHP) $(PHPUNIT_COMMAND) $(ARGS)

composer.json

@@ -30,11 +30,13 @@
 	"require": {
 		"php": ">=7.4.0 <8.3.0",
 		"dragonmantank/cron-expression": "^3.3.0",
+		"symfony/intl": "^5.4.35|^6.4.3|^7.0.3",
 		"symfony/polyfill-php80": "^1.29"
 	},
 	"require-dev": {
 		"brianium/paratest": "^6.3.0",
 		"infection/infection": "^0.26.0",
+		"nette/utils": "^3.1.0|^4.0.0",
 		"orisai/coding-standard": "^3.0.0",
 		"phpstan/extension-installer": "^1.0.0",
 		"phpstan/phpstan": "^1.0.0",

docs/README.md

@@ -8,7 +8,7 @@ Human-readable cron expressions
 - [Usage](#usage)
 - [Seconds](#seconds)
 - [Time zones](#time-zones)
-- [Translations](#translations)
+- [Localization](#localization)
 - [Handling unsupported expressions](#handling-unsupported-expressions)
 - [Compatibility](#compatibility)
 
@@ -22,6 +22,8 @@ composer require orisai/cron-expression-explainer
 
 ## Usage
 
+Explain any cron expression
+
 ```php
 use Orisai\CronExpressionExplainer\DefaultCronExpressionExplainer;
 
@@ -45,6 +47,10 @@ $explainer->explain('* * * * 7L'); // At every minute on the last Sunday.
 
 ## Seconds
 
+Add amount of seconds after which expression should match again
+
+> This is a feature of [orisai/scheduler](https://github.com/orisai/scheduler)
+
 ```php
 $explainer->explain('* * * * *', 1); // At every second.
 $explainer->explain('* * * * *', 30); // At every 30 seconds.
@@ -54,21 +60,34 @@ $explainer->explain('1 * * * *', 2); // At every 2 seconds at minute 1.
 
 ## Time zones
 
+Add timezone in which the cron expression should be interpreted
+
+> This is a feature of [orisai/scheduler](https://github.com/orisai/scheduler)
+
 ```php
 use DateTimeZone;
 
 $explainer->explain('30 10 * * *', null, new DateTimeZone('America/New_York')); // At 10:30 in America/New_York time zone.
 ```
 
-## Translations
+## Localization
 
-Yeah, localization is actually not supported (yet). But the interface is ready for it!
+Translate expression into any supported locale
 
 ```php
-$explainer->getSupportedLanguages(); // array<string, string> e.g. ['en' => 'english']
-$explainer->explain('* * * * *', null, null, 'en');
+$explainer->explain('* * * * *', null, null, 'en'); // At every minute.
+$explainer->explain('* * * * *', null, null, 'cs'); // Každou minutu.
+$explainer->getSupportedLocales(); // array<string, string> e.g. ['en' => 'english', 'cs' => 'czech', /* ... */]
+$explainer->setDefaultLocale('cs');
 ```
 
+Currently supported locales are:
+
+- `cs` - czech / čeština
+- `en` - english
+
+In case given locale is not supported, the `UnsupportedLocale` exception is thrown.
+
 ## Handling unsupported expressions
 
 Syntax may not be recognized as valid or may just be some complex variant that we don't support (yet).
@@ -89,3 +108,14 @@ try {
 This library is built on top of [dragonmantank/cron-expression](https://github.com/dragonmantank/cron-expression).
 For best compatibility, use it to interpret your expressions.
 For example with [orisai/scheduler](https://github.com/orisai/scheduler)!
+
+## Contributing
+
+To add support for a new locale:
+
+- create file in `src/Translator/translations` and add translations for all the keys used in other translation files
+- add it to supported locales in `DefaultCronExpressionExplainer`
+- generate translations via `make update-snapshots`
+- verify that the generated test translations in `tests/Snapshots/translations` make sense and match their configuration
+- run `make tests`, it should pass now :)
+- mention the locale in the documentation

src/CronExpressionExplainer.php

@@ -4,26 +4,39 @@
 
 use DateTimeZone;
 use Orisai\CronExpressionExplainer\Exception\UnsupportedExpression;
-use Orisai\CronExpressionExplainer\Exception\UnsupportedLanguage;
+use Orisai\CronExpressionExplainer\Exception\UnsupportedLocale;
 
 interface CronExpressionExplainer
 {
 
 	/**
 	 * @param int<0,59>|null $repeatSeconds
 	 * @throws UnsupportedExpression
-	 * @throws UnsupportedLanguage
+	 * @throws UnsupportedLocale
 	 */
 	public function explain(
 		string $expression,
 		?int $repeatSeconds = null,
 		?DateTimeZone $timeZone = null,
-		?string $language = null
+		?string $locale = null
 	): string;
 
+	/**
+	 * @template T of string
+	 * @param list<T> $locales
+	 * @param int<0, 59>|null $repeatSeconds
+	 * @return array<T, string>
+	 */
+	public function explainInLocales(
+		array $locales,
+		string $expression,
+		?int $repeatSeconds = null,
+		?DateTimeZone $timeZone = null
+	): array;
+
 	/**
 	 * @return array<string, string>
 	 */
-	public function getSupportedLanguages(): array;
+	public function getSupportedLocales(): array;
 
 }