---
title: Validation and Coverage Checks | Shopware Community Hub
description: >-
  Learn how to validate translations and measure coverage for snippets and DAL
  using PHPUnuhi, including CI integration.
canonical_url: 'https://hub.shopware.com/learn/unit/validation-and-coverage-checks'
---

# Validation and Coverage Checks

<LearningObjectives>

- Understand the purpose of automated translation validation and coverage checks.
- Use PHPUnuhi to validate snippet files and measure translation coverage.
- Validate DAL-based entity translations for completeness and consistency.
- Keep snippet JSONs and entity translations in sync across locales.
- Integrate automated checks and autofixes into CI pipelines.
  
</LearningObjectives>

# Validation and Coverage Checks

As soon as a project supports multiple languages, manual checks for missing translations stop scaling. It becomes easy to overlook missing keys, incomplete locales, or inconsistent translations.

PHPUnuhi is a lightweight tool that helps you to validate translations, measure coverage, and detect problems early. It works with both snippet files and Shopware DAL-based entity translations, and it integrates well into development workflows as well as CI/CD pipelines.

By using automated checks, you can prevent translation regressions before they reach production.

**Reference:** [PHPUnuhi](https://github.com/boxblinkracer/phpunuhi)

## Installation

```bash
composer require boxblinkracer/phpunuhi --dev
```

Create `phpunuhi.xml` at your project root. This defines translation sets, storage format(s), locales, and optional filters.

## Validating Snippet Files (JSON)

Example configuration for Administration/Storefront snippet sets:

```xml
<phpunuhi
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="./vendor/boxblinkracer/phpunuhi/config.xsd">
    <translations>
        <set name="Administration">
            <format>
                <json indent="4" sort="true"/>
            </format>
            <locales>
                <locale name="en-GB">./Resources/snippet/en-GB/administration.json</locale>
                <locale name="de-DE">./Resources/snippet/de-DE/administration.json</locale>
            </locales>
        </set>
        <set name="Storefront">
            <format>
                <json indent="4" sort="true"/>
            </format>
            <locales>
                <locale name="en-GB">./Resources/snippet/en-GB/storefront.json</locale>
                <locale name="de-DE">./Resources/snippet/de-DE/storefront.json</locale>
            </locales>
        </set>
    </translations>
</phpunuhi>
```

Run validations and coverage:

```bash
# Validate structures and keys across locales
php vendor/bin/phpunuhi validate

# Show per-set coverage (how many keys translated per locale)
php vendor/bin/phpunuhi status

# Autofix structure (indent, sorting, normalize)
php vendor/bin/phpunuhi fix:structure
```

Optionally, auto-translate missing entries (review results before merging):

```bash
# Google Web (quick, may rate-limit)
php vendor/bin/phpunuhi translate --service=googleweb

# DeepL or OpenAI (requires API keys)
php vendor/bin/phpunuhi translate --service=deepl --deepl-key=$DEEPL_KEY
php vendor/bin/phpunuhi translate --service=openai --openai-key=$OPENAI_KEY
```

Export/import for collaboration (e.g., agencies):

```bash
# Export to CSV or HTML for external editing
php vendor/bin/phpunuhi export --format=csv   --output=./translations
php vendor/bin/phpunuhi export --format=html  --output=./translations

# Import updates back
php vendor/bin/phpunuhi import --format=csv   --input=./translations
```

## Validating Entity Translations (DAL)

PHPUnuhi can read Shopware translations directly from the database to validate coverage of translatable entity fields.

Add a DB-backed set to `phpunuhi.xml`:

```xml
<phpunuhi
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="./vendor/boxblinkracer/phpunuhi/config.xsd">
    <php>
        <env name="DB_HOST" value="127.0.0.1"/>
        <env name="DB_PORT" value="3306"/>
        <env name="DB_USER" value=""/>
        <env name="DB_PASSWD" value=""/>
        <env name="DB_DBNAME" value="shopware"/>
    </php>

    <translations>
        <set name="Products">
            <format>
                <shopware6 entity="product"/>
            </format>
            <filter>
                <include>
                    <key>name</key>
                    <key>description</key>
                    <key>metaTitle</key>
                </include>
            </filter>
            <locales>
                <locale name="en-GB"/>
                <locale name="de-DE"/>
            </locales>
        </set>
    </translations>
</phpunuhi>
```

Now run:

```bash
# Coverage across product translations
php vendor/bin/phpunuhi status

# (Optional) translate missing values using a service
php vendor/bin/phpunuhi translate --service=deepl --deepl-key=$DEEPL_KEY
```

**Tip:** Create multiple sets (e.g., shipping methods, categories) or narrow `include` keys for essential fields.

## CI/CD Integration

Fail builds when coverage drops or keys are missing. Minimal GitHub Actions example:

```yaml
name: i18n-validation
on: [pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.3'
      - name: Install PHPUnuhi
        run: composer install --no-interaction --no-progress
      - name: Validate translations
        run: |
          php vendor/bin/phpunuhi fix:structure
          php vendor/bin/phpunuhi validate
          php vendor/bin/phpunuhi status
```

**Recommended gates:**

- Enforce 0 missing for release branches; allow small drift on feature branches.
- Export reports (CSV/HTML) as artifacts for reviewers.

## Best Practices

- Keep snippet keys stable; deprecate before removal.
- Always review machine translations before merging.
- Version snippet files alongside code changes.
- Create focused DB sets with `include` filters for required fields.
- Track coverage trends per set and locale.

## Summary

In this learning unit, you learned:

- Why manual translation checks do not scale in larger or multilingual projects.
- How PHPUnuhi can be used to validate snippet files and measure translation coverage.
- How to check DAL-based entity translations for completeness and consistency.
- How automated validation helps prevent translation regressions.
- How translation checks can be integrated into CI pipelines.

With these practices in place, you can ensure that translations remain consistent, complete, and reviewable as your project grows.