Hebrew Code & Data Support

Relevant source files

The following files were used as context for generating this wiki page:

• BY-STACK/hebrew-source.md
• claude-md-snippets/hebrew.md
• README.md
• INTEGRATION.md
• CRITICAL-PATTERNS.md
• bugbot-rules/hebrew-source-and-data.md

Hebrew Code & Data Support is a specialized configuration and set of patterns designed to handle the unique challenges of using Hebrew characters within source code, data processing, and user interfaces. In this project, Hebrew is utilized for code comments, user-generated content, and specific string literals, requiring robust handling to prevent silent failures or security vulnerabilities.

The scope of this support covers Bidirectional (BiDi) control characters in source files, non-ASCII string comparison, HTTP header encoding constraints, and search normalization. By centralizing these patterns, the project ensures that standard development tools (like linters and debuggers) and core logic (like authentication and search) function correctly in a Hebrew-enabled environment.

Sources: BY-STACK/hebrew-source.md:1-10, README.md:25-27, claude-md-snippets/hebrew.md:1-2

Bidirectional (BiDi) Source Code Protection

Bidirectional control characters (e.g., U+200F, U+200E) are invisible characters often introduced when copying Hebrew text from browsers or chat applications. While they assist in rendering text direction, they can cause security vulnerabilities (Trojan Source) or lead to failures in CI/CD pipelines because linters such as bandit (B613) and ruff (PLE2502) flag them as high-risk issues.

BiDi Control Characters Overview

Character	Unicode	Name	Effect
RLM	U+200F	RIGHT-TO-LEFT MARK	Forces RTL direction
LRM	U+200E	LEFT-TO-RIGHT MARK	Forces LTR direction
Embedding	U+202A–U+202E	LRE, RLE, PDF, LRO, RLO	Nested directional overrides
Isolate	U+2066–U+2069	LRI, RLI, FSI, PDI	Directional isolation

Sources: BY-STACK/hebrew-source.md:15-32, claude-md-snippets/hebrew.md:4-7

Validation Logic

To prevent these characters from entering the codebase, a specific scanning test is implemented. This test must use escape sequences (e.g., \u200f) instead of literal characters to avoid triggering the same linter failures it is meant to detect.

Data Processing and Security

Non-ASCII String Comparison

Functions like secrets.compare_digest are optimized for constant-time comparison to prevent timing attacks but are often restricted to ASCII-only strings or bytes. Passing Hebrew strings directly can result in a TypeError.

Implementation Pattern:
Always encode both the expected and given strings to UTF-8 before comparison.

# Sources: [BY-STACK/hebrew-source.md:83-85]
secrets.compare_digest(expected.encode("utf-8"), given.encode("utf-8"))

Sources: BY-STACK/hebrew-source.md:73-85, claude-md-snippets/hebrew.md:9-11

HTTP Header Constraints

Standard HTTP headers (RFC 9110) do not natively support UTF-8. Tokens or identifiers containing Hebrew characters may break at the client-side or during transmission if they do not adhere to specific grammar (e.g., token68 for Bearer auth).

Hebrew Search Normalization

Searching Hebrew text requires normalization to handle Diacritics (Nikud) and Final Letters (Sofiot), which change the character's Unicode value without changing the word's meaning.

Normalization Requirements

1. Nikud (Diacritics): Characters in the range U+0591–U+05C7 must be stripped from both the query and the indexed content.
2. Final Letters (Sofiot): Characters like ךםןףץ are distinct Unicode points. Precise matching requires mapping these to their non-final counterparts or using linguistic stemming.

Sources: BY-STACK/hebrew-source.md:112-127, claude-md-snippets/hebrew.md:18-19

User Interface and Error Handling

For Israeli users, error messages should be localized and generic to maintain privacy and security (linked to CRITICAL K6). Detailed technical stack traces or internal IDs must be kept in the server logs and never leaked to the client.

Requirement	Description	Implementation
Language	Hebrew	All user-facing alerts/messages
Privacy	Generic Content	Do not include internal IDs or logic reasons
Logging	English/Technical	Full stack traces and PII-safe technical details

Sources: BY-STACK/hebrew-source.md:132-137, claude-md-snippets/hebrew.md:21-21, CRITICAL-PATTERNS.md:36-39

Hebrew Code & Data Support ensures that Hebrew-speaking users and developers can interact with the system without compromising security or reliability. By enforcing invisible character checks, proper byte-encoding for security functions, and normalization for search, the system avoids the "silent failures" typical of RTL and non-ASCII implementations.

Sources: BY-STACK/hebrew-source.md, INTEGRATION.md:148-150