Magic comments

caution

The Tolgee CLI is currently experimental and subject to bugs. Breaking changes may happen before stable release!

Help us reach stable version faster by reporting any bug you encounter on the issue tracker. Feedback is also greatly appreciated!

In some cases, you may need to be explicit about what you want the extractor to do, because it's getting something wrong or because of a very specific use case. Magic comments to the rescue! They're a set of directives you can add to your code that'll explicitly tell the CLI what it should do.

Usage

As their name implies, they're written as comments. You probably already encountered some form of them with your code linter, or type checker.

Here is an example usage:

import React from 'react'
import { T } from '@tolgee/react'

export default function MyComponent () {
  return (
    <section>
      <h2><T keyName='section-title'>My title!</T></h2>
      {/* @tolgee-ignore */}
      <p><T keyName='section-text'>Section text!</T></p>
    </section>
  )
}

Here, the @tolgee-ignore directive will tell the CLI to skip parsing the next line, and it will not include it in the extraction result. Only section-title would be considered a string.

Available directives

@tolgee-ignore

Ignores the next line. Keys that might be present will not be extracted and warnings that would've been emitted will be suppressed as well.

info

If the ignore directive does not have any effect, a warning will be emitted.

@tolgee-key

Specified a localization key. It can be written in 2 forms: simple or detailed.

The simple form just takes the key name as an argument. The detailed form takes a JSON5 object, that takes the keyName, ns, and defaultValue properties.

// @tolgee-key simple-key
// @tolgee-key { keyName: 'detailed-key', ns: 'my-namespace' }

If it is set before a key that would've been extracted, the comment supersedes what would've been extracted and suppresses warnings that would have been emitted. Think of it as an implicit @tolgee-ignore.