feat: disable KeyNamingConventionValidator by default (#158)

Author: konradmichalik

CHANGELOG.md

@@ -7,6 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+- feat[!!!]: skip KeyNamingConventionValidator by default (opt-in to reduce false positives)
 - feat: provide a standalone PHAR distribution for CI and non-Composer projects
 
 ## [1.5.0] - 2026-06-29

docs/configuration/index.md

@@ -59,15 +59,18 @@ When the same option is specified in multiple places, this priority applies:
 2. **Configuration file**
 3. **Default values** (lowest priority)
 
-## DuplicateValuesValidator
+## Opt-In Validators
 
 ::: info
-The `DuplicateValuesValidator` is disabled by default to reduce noise in validation results, as duplicate values are often intentional (e.g., common button labels like "OK" or "Cancel").
+The `DuplicateValuesValidator` and the `KeyNamingConventionValidator` are disabled by default to reduce noise in validation results:
+
+- **DuplicateValuesValidator** — duplicate values are often intentional (e.g., common button labels like "OK" or "Cancel").
+- **KeyNamingConventionValidator** — auto-detected naming conventions frequently produce false positives on mixed but intentional key styles.
 :::
 
-To enable it, either:
+To enable one of them, either:
 - Use `--only` to explicitly include it
-- Set `skip: []` in your configuration file
+- Set `skip: []` in your configuration file (enables all validators)
 
 ## Next Steps
 

docs/reference/validators.md

@@ -437,10 +437,29 @@ Enforces consistent naming patterns for translation keys.
 
 **Result:** WARNING
 
+::: info Opt-In Validator
+This validator is disabled by default, as auto-detected naming conventions often produce false positives on mixed but intentional key styles. Enable it when you want to enforce a convention.
+:::
+
 ::: tip
 This validator auto-detects the most common pattern in your files. Configure a specific convention for strict enforcement.
 :::
 
+### Enable via CLI
+
+```bash
+composer validate-translations translations/ \
+  --only "MoveElevator\\ComposerTranslationValidator\\Validator\\KeyNamingConventionValidator"
+```
+
+### Enable via Configuration
+
+```yaml
+paths:
+  - translations/
+skip: []  # Empty skip list enables all validators
+```
+
 ### Supported Conventions
 
 | Convention | Example |

src/Command/TranslationValidationBehavior.php

@@ -133,7 +133,7 @@ protected function configure(): void
   • <info>EmptyValuesValidator</info>     - Finds empty or whitespace-only translation values
   • <info>EncodingValidator</info>        - Validates file encoding and character issues
   • <info>HtmlTagValidator</info>         - Validates HTML tag consistency across translations
-  • <info>KeyNamingConventionValidator</info> - Validates translation key naming conventions
+  • <info>KeyNamingConventionValidator</info> - Validates translation key naming conventions (opt-in, disabled by default)
   • <info>KeyCountValidator</info>        - Warns when a file exceeds the key count threshold
   • <info>KeyDepthValidator</info>        - Warns when keys exceed the nesting depth threshold
   • <info>PlaceholderConsistencyValidator</info> - Validates placeholder consistency across files

src/Config/TranslationValidatorConfig.php

@@ -13,7 +13,7 @@
 
 namespace MoveElevator\ComposerTranslationValidator\Config;
 
-use MoveElevator\ComposerTranslationValidator\Validator\DuplicateValuesValidator;
+use MoveElevator\ComposerTranslationValidator\Validator\{DuplicateValuesValidator, KeyNamingConventionValidator};
 
 /**
  * TranslationValidatorConfig.
@@ -38,9 +38,15 @@ class TranslationValidatorConfig
     /** @var string[] */
     private array $only = [];
 
-    /** @var string[] */
+    /**
+     * Validators disabled by default (opt-in). They produce too many
+     * intentional/false-positive findings to run unconditionally.
+     *
+     * @var string[]
+     */
     private array $skip = [
         DuplicateValuesValidator::class,
+        KeyNamingConventionValidator::class,
     ];
 
     /** @var string[] */

tests/src/Config/ConfigFactoryTest.php

@@ -73,7 +73,10 @@ public function testCreateFromArrayWithEmptyData(): void
         $this->assertSame([], $config->getFileDetectors());
         $this->assertSame([], $config->getParsers());
         $this->assertSame([], $config->getOnly());
-        $this->assertSame([\MoveElevator\ComposerTranslationValidator\Validator\DuplicateValuesValidator::class], $config->getSkip());
+        $this->assertSame([
+            \MoveElevator\ComposerTranslationValidator\Validator\DuplicateValuesValidator::class,
+            \MoveElevator\ComposerTranslationValidator\Validator\KeyNamingConventionValidator::class,
+        ], $config->getSkip());
         $this->assertSame([], $config->getExclude());
         $this->assertFalse($config->getStrict());
         $this->assertFalse($config->getDryRun());

tests/src/Config/TranslationValidatorConfigTest.php

@@ -14,7 +14,7 @@
 namespace MoveElevator\ComposerTranslationValidator\Tests\Config;
 
 use MoveElevator\ComposerTranslationValidator\Config\TranslationValidatorConfig;
-use MoveElevator\ComposerTranslationValidator\Validator\DuplicateValuesValidator;
+use MoveElevator\ComposerTranslationValidator\Validator\{DuplicateValuesValidator, KeyNamingConventionValidator};
 use PHPUnit\Framework\Attributes\{CoversClass, DataProvider};
 use PHPUnit\Framework\TestCase;
 
@@ -84,7 +84,7 @@ public static function adderProvider(): iterable
         yield 'addFileDetector' => ['addFileDetector', 'getFileDetectors', 'SomeFileDetector', ['SomeFileDetector']];
         yield 'addParser' => ['addParser', 'getParsers', 'SomeParser', ['SomeParser']];
         yield 'only' => ['only', 'getOnly', 'OnlyValidator', ['OnlyValidator']];
-        yield 'skip' => ['skip', 'getSkip', 'SkipValidator', [DuplicateValuesValidator::class, 'SkipValidator']];
+        yield 'skip' => ['skip', 'getSkip', 'SkipValidator', [DuplicateValuesValidator::class, KeyNamingConventionValidator::class, 'SkipValidator']];
     }
 
     public function testDefaultValues(): void
@@ -94,7 +94,7 @@ public function testDefaultValues(): void
         $this->assertSame([], $this->config->getFileDetectors());
         $this->assertSame([], $this->config->getParsers());
         $this->assertSame([], $this->config->getOnly());
-        $this->assertSame([DuplicateValuesValidator::class], $this->config->getSkip());
+        $this->assertSame([DuplicateValuesValidator::class, KeyNamingConventionValidator::class], $this->config->getSkip());
         $this->assertSame([], $this->config->getExclude());
         $this->assertFalse($this->config->getStrict());
         $this->assertFalse($this->config->getDryRun());
@@ -152,7 +152,7 @@ public static function toArrayProvider(): iterable
             'file-detectors' => [],
             'parsers' => [],
             'only' => [],
-            'skip' => [DuplicateValuesValidator::class],
+            'skip' => [DuplicateValuesValidator::class, KeyNamingConventionValidator::class],
             'exclude' => [],
             'strict' => false,
             'dry-run' => false,