> ## Documentation Index
> Fetch the complete documentation index at: https://glotctl.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# How Detection Works

> Understanding glot's static analysis capabilities and supported patterns

Glot uses static analysis to detect i18n issues in your codebase. This page documents all supported patterns and known limitations.

## Hardcoded Text Detection

### JSX Text Nodes

Glot detects text content in JSX elements:

```tsx theme={null}
<div>Hello World</div>           // Detected
<>text in fragment</>            // Detected
<div>
  Multiline                      // Detected
  text content
</div>
```

### JSX Expression Containers

**String literal** - detected:

```tsx theme={null}
<div>{"Submit"}</div>
```

**Ternary expression** - both branches checked:

```tsx theme={null}
{loading ? "Loading..." : "Done"}
```

**Logical AND** - right side checked:

```tsx theme={null}
{error && "Something wrong"}
```

**Logical OR** - right side checked:

```tsx theme={null}
{value || "Default"}
```

**Template literal** - static parts checked:

```tsx theme={null}
{`Hello ${name}`}
```

### Checked Attributes

By default, glot checks these attributes for hardcoded text:

* `placeholder` - Input placeholder text
* `title` - Tooltip/title text
* `alt` - Image alternative text
* `aria-label` - Accessibility label
* `aria-description` - Accessibility description
* `aria-placeholder` - Accessibility placeholder
* `aria-roledescription` - Accessibility role description
* `aria-valuetext` - Accessibility value text

<Tip>
  Customize checked attributes via `checkedAttributes` in `.glotrc.json`.
</Tip>

### Skipped Patterns

The following are NOT reported as hardcoded text:

**Pure numbers** - no alphabetic characters:

```tsx theme={null}
<div>123</div>
```

**Pure symbols** - no alphabetic characters:

```tsx theme={null}
<div>---</div>
<div>$100</div>
```

**Empty/whitespace** - no content:

```tsx theme={null}
<div>   </div>
```

**Style tag content** - CSS code:

```tsx theme={null}
<style>{`.class { color: red }`}</style>
```

**Configured ignores** - text matching patterns in `ignoreTexts` config.

### Text Detection Rules

Glot uses Unicode `char::is_alphabetic()` to determine if text should be reported. This means:

* All languages are supported (English, Chinese, Japanese, Arabic, etc.)
* Text must contain at least one alphabetic character
* Numbers and symbols alone are ignored

***

## Translation Function Tracking

Glot tracks how translation functions (`t`) are obtained and used throughout your codebase.

### Direct Binding

The most common pattern - calling `useTranslations` or `getTranslations` directly:

```tsx theme={null}
// Client components
const t = useTranslations("Namespace");
const t = useTranslations();  // Without namespace

// Server components
const t = await getTranslations("Namespace");
const t = await getTranslations();

// Renamed binding
const translate = useTranslations("Namespace");
```

### Props Passing

When a translation function is passed as a prop to a child component:

```tsx theme={null}
// Parent component
function Page() {
  const t = useTranslations("Landing");
  return <LandingContent t={t} />;
}

// Child component - all these patterns are supported:
function Component({ t }: Props) { ... }                    // Function declaration
const Component = ({ t }: Props) => { ... }                 // Arrow function
function Component({ t: translate }: Props) { ... }         // Renamed destructuring
function Component({ t = defaultT }: Props) { ... }         // Default value
function Component({ t: translate = defaultT }: Props) { ...} // Both
```

Member expression component names are also supported:

```tsx theme={null}
<UI.Button t={t} />
```

### Function Call Arguments

When a translation function is passed to a utility/factory function:

```tsx theme={null}
// Factory function receiving t as parameter
const usageTypeLabels = (t: ReturnType<typeof useTranslations>) => ({
  ai_chapter: t("usageTypes.ai_chapter"),
  ai_completion: t("usageTypes.ai_completion"),
});

// Usage
const t = useTranslations("CreditsUsageList");
const labels = usageTypeLabels(t);  // Keys are tracked correctly
```

Supported patterns:

```tsx theme={null}
const labels = usageLabels(t);                    // Regular function call
const labels = (t) => ({ key: t("key") });        // Arrow function
function buildLabels(t) { return t("key"); }      // Function declaration
export default function(t) { ... }                // Default export
export default (t) => ...                         // Arrow default export
```

### Translation Method Calls

All next-intl translation methods are supported:

```tsx theme={null}
t("key")                              // Basic call
t.raw("htmlContent")                  // Raw string
t.rich("text", { bold: (c) => <b>{c}</b> })  // Rich text
t.markup("text")                      // Markup
```

***

## Dynamic Key Resolution

Glot can resolve dynamic keys in many common patterns.

### Object Access Pattern

When a key comes from an object property:

```tsx theme={null}
const toolKeys = {
  create: "createNovel",
  update: "updateNovel",
};

const key = toolKeys[toolName];
t(key);  // Resolves to: createNovel, updateNovel
```

### Array Iteration

Supported iterator methods: `map`, `forEach`, `filter`, `find`, `some`, `every`, `flatMap`

**Object array with property access:**

```tsx theme={null}
const capabilities = [
  { titleKey: "novelManagement" },
  { titleKey: "characterDevelopment" },
];

capabilities.map(cap => t(`features.${cap.titleKey}.title`));
// Resolves to: features.novelManagement.title, features.characterDevelopment.title
```

**String array:**

```tsx theme={null}
const FEATURE_KEYS = ["save", "characters", "chapters"] as const;

FEATURE_KEYS.map(key => t(`features.${key}`));
// Resolves to: features.save, features.characters, features.chapters
```

### Template Literals

Templates with a single dynamic expression are analyzed:

```tsx theme={null}
t(`prefix.${cap.titleKey}.suffix`);
// Analyzed as: prefix + dynamic value + suffix
```

### Conditional Expressions

Both branches of conditionals are extracted:

```tsx theme={null}
t(cond ? "keyA" : "keyB");                    // Both keys tracked
t(key || "fallback");                         // Logical OR as fallback
t(flag1 ? (flag2 ? "a" : "b") : "c");         // Nested conditionals
```

### Cross-File Import Resolution

Glot resolves imports from other files:

```tsx theme={null}
// utils/keys.ts
export const toolKeys = { create: "createNovel", update: "updateNovel" };

// page.tsx
import { toolKeys } from "./utils/keys";
const key = toolKeys[toolName];
t(key);  // Resolves correctly across files
```

<Note>
  Only module-level, exported declarations are resolved across files.
</Note>

***

## Schema Factory Pattern

Glot detects translation keys in schema factory functions (commonly used with Zod):

```tsx theme={null}
export const createSchema = (t: TFunction) => z.object({
  title: z.string().min(1, t("titleRequired")),
  description: z.string().max(100, t("descriptionMax")),
});

// When called with: createSchema(t) where t = useTranslations("Form")
// Keys tracked: Form.titleRequired, Form.descriptionMax
```

**Supported patterns:**

* Arrow function exports: `export const createSchema = (t) => ...`
* Parameter names starting with `t`: `t`, `tForm`, `tValidation`
* Nested schema calls are tracked

***

## Scope Isolation

Glot correctly handles variable scoping and shadowing.

### Parameter Shadowing

Inner bindings shadow outer ones:

```tsx theme={null}
const t = useTranslations("Outer");

function Child() {
  const t = useTranslations("Inner");  // Shadows module-level t
  return t("key");  // Uses "Inner" namespace
}

function Parent() {
  return t("key");  // Uses "Outer" namespace
}
```

### Sibling Function Isolation

Translation bindings don't leak between sibling functions:

```tsx theme={null}
function ComponentA() {
  const t = useTranslations("A");
  return t("key");  // Tracked with "A"
}

function ComponentB() {
  // t is not defined here
  return t("key");  // NOT tracked
}
```

### Iterator Scope

Nested iterators with same variable names are handled correctly:

```tsx theme={null}
OUTER.map(item => (
  <>
    {t(`outer.${item.key}`)}
    {INNER.map(item => t(`inner.${item.key}`))}  // Correctly shadows outer item
  </>
))
```

***

## glot-message-keys Annotation

For dynamic keys that can't be statically analyzed, use `glot-message-keys` to declare expected keys. This tells glot which keys are actually used, enabling safe cleanup with `glot clean` and suppressing unresolved key warnings.

```tsx theme={null}
// glot-message-keys "Status.active", "Status.inactive", "Status.pending"
t(status);

// Glob patterns
// glot-message-keys "errors.*"
t(`errors.${code}`);
```

You can also auto-insert these annotations with `glot fix --apply`.

<Tip>
  For full syntax (absolute patterns, relative patterns, glob matching, JSX comments), see [Directives — Dynamic Key Declaration](/directives#dynamic-key-declaration).
</Tip>

***

## Limitations

### Patterns That Cannot Be Tracked

These patterns cannot be tracked by static analysis and have no workaround:

**Non-destructured props** - use destructuring instead:

```tsx theme={null}
// NOT supported
function Component(props) {
  return props.t("key");
}

// Supported
function Component({ t }) {
  return t("key");
}
```

**Deep nested destructuring** - use top-level destructuring:

```tsx theme={null}
// NOT supported
function Component({ translations: { t } }) {
  return t("key");
}

// Supported
function Component({ t }) {
  return t("key");
}
```

### Patterns Requiring Declaration

These patterns cannot be statically analyzed but can be handled with `glot-message-keys`:

**Multi-expression template**:

```tsx theme={null}
// glot-message-keys "Namespace.some.key"
t(`${prefix}.${suffix}`);
```

**Logical AND as key**:

```tsx theme={null}
// glot-message-keys "Namespace.key"
t(flag && "key");
```

**Runtime dynamic key**:

```tsx theme={null}
// glot-message-keys "Namespace.key"
t(getKeyFromApi());
```

### Feature-Specific Limitations

**Cross-file key object resolution:**

Objects with spread operators are not collected for cross-file resolution:

```tsx theme={null}
// Collected
export const keys = { a: "keyA", b: "keyB" };

// NOT collected (spread operator)
export const extended = { ...keys, c: "keyC" };
```

This only affects dynamic key resolution via object access patterns. Direct `t()` calls are unaffected.

**Schema factory detection:**

Only arrow function exports are supported:

```tsx theme={null}
// Supported
export const createSchema = (t) => z.object({ ... });

// NOT supported
export function createSchema(t) { return z.object({ ... }); }
```

***

## TypeScript Support

Glot automatically unwraps TypeScript-specific syntax:

```tsx theme={null}
// All of these are analyzed correctly
"text" as const
"text" as string
"text" satisfies string
("text")  // Parentheses
```