symfony/symfony · error · Twig\Error\SyntaxError

A message inside a trans tag must be a simple text.

Error message

A message inside a trans tag must be a simple text.

What it means

Thrown by the {% trans %} token parser when the body between {% trans %} and {% endtrans %} is not a single TextNode or an AbstractExpression. The trans tag requires its message to be a translatable unit (pure static text, optionally with placeholder expressions), so compound nodes like nested blocks, HTML elements, or multiple concatenated pieces are rejected.

Source

Thrown at src/Symfony/Bridge/Twig/TokenParser/TransTokenParser.php:73

                $stream->next();
                $domain = $this->parser->parseExpression();
            }

            if ($stream->test('into')) {
                // {% trans into "fr" %}
                $stream->next();
                $locale = $this->parser->parseExpression();
            } elseif (!$stream->test(Token::BLOCK_END_TYPE)) {
                throw new SyntaxError('Unexpected token. Twig was looking for the "with", "from", or "into" keyword.', $stream->getCurrent()->getLine(), $stream->getSourceContext());
            }
        }

        // {% trans %}message{% endtrans %}
        $stream->expect(Token::BLOCK_END_TYPE);
        $body = $this->parser->subparse($this->decideTransFork(...), true);

        if (!$body instanceof TextNode && !$body instanceof AbstractExpression) {
            throw new SyntaxError('A message inside a trans tag must be a simple text.', $body->getTemplateLine(), $stream->getSourceContext());
        }

        $stream->expect(Token::BLOCK_END_TYPE);

        return new TransNode($body, $domain, $count, $vars, $locale, $lineno);
    }

    public function decideTransFork(Token $token): bool
    {
        return $token->test(['endtrans']);
    }

    public function getTag(): string
    {
        return 'trans';
    }
}

View on GitHub (pinned to 698e28026c)

Solutions

1. Keep the trans body to plain static text only, e.g. {% trans %}Hello{% endtrans %}.
2. For dynamic content, use placeholders: {% trans %}Hello %name%{% endtrans %} with {% trans with {'%name%': user.name} %}.
3. Move complex/nested markup outside the trans tag and translate only the static sentence.

Example fix

// before
{% trans %}
  <p>Hello {{ user.name }}</p>
{% endtrans %}

// after
<p>{% trans with {'%name%': user.name} %}Hello %name%{% endtrans %}</p>

// Validate trans bodies with the linter before deploying
// php bin/console lint:twig templates/
// Keep trans bodies to plain text + %placeholder% expressions only.

try {
    $twig->render($template, $vars);
} catch (\Twig\Error\SyntaxError $e) {
    if (str_contains($e->getMessage(), 'must be a simple text')) {
        // simplify the trans body to plain text
    }
    throw $e;
}

When it happens

Trigger: Placing non-text content inside the trans tag such as nested {% %} blocks, raw HTML tags that produce non-TextNode AST, or multi-node bodies that subparse into something other than TextNode/AbstractExpression.

Common situations: Wrapping a complex template fragment in {% trans %}...{% endtrans %} that includes conditionals, loops, or HTML. Attempting to translate a block that contains variable interpolations beyond simple %placeholder% expressions. Mixing trans with trans_default_domain incorrectly.

Related errors

• Unexpected token. Twig was looking for the "with", "from", o
• The "app.locale" variable is not available.
• The "app.enabled_locales" variable is not available.
• You cannot use the "%s" if the Translation Contracts are not
• Argument 2 passed to "%s()" must be a locale passed as a str

AI-assisted analysis of symfony/symfony@698e28026c (2026-08-06). Data as JSON: /api/errors/4fde1f4033d41f6d. Report an issue: GitHub.