Skip to content

docs: restructure usage examples and add context7 configuration#86

Merged
paullla merged 1 commit into
Locastic:masterfrom
paullla:docs/context7-and-usage-examples
Jul 8, 2026
Merged

docs: restructure usage examples and add context7 configuration#86
paullla merged 1 commit into
Locastic:masterfrom
paullla:docs/context7-and-usage-examples

Conversation

@paullla

@paullla paullla commented Jul 8, 2026

Copy link
Copy Markdown
Member
Q A
Bug fix? no
New feature? no
BC breaks? no
Deprecations? no
Issues -
License MIT

Problem

The README's usage examples sit under a single vague "Usage" heading as bold pseudo-headings, which reads fine on GitHub but retrieves poorly in documentation indexes such as Context7 that serve snippets to AI coding agents by nearest heading. PATCH is the recommended way to edit translations but the only edit example showed the PUT payload with ids, there was no response example for ?groups[]=translations, and known limitations (filtering by translated fields, the per-item translation query on collections) were undocumented, which leads agents to invent answers instead of stating they are not supported. The bundle is also not yet indexed on Context7, so agents answer questions about it from stale training data.

Changes

  • Restructure the usage section into task-oriented headings, each with a self-contained example: request a single locale (query param and Accept-Language as full request lines), return all translations (now with a response example showing the group is additive), create with POST, update with PATCH, replace with PUT.
  • Add a merge patch example: one locale submitted, no ids needed, other locales untouched.
  • Prefix the PUT example with its full-replace semantics and a link to the standard_put notes.
  • Add a limitations section: no filtering/ordering by translated fields, and one translation query per collection item (EXTRA_LAZY, no built-in eager loading).
  • Normalize code fence info strings (``` php to ```php).
  • Add context7.json, validated against the published schema: indexes only README, changelog and upgrade guides (excludes src, tests, config, bin), eleven usage rules covering the conventions and footguns (serialization groups, payload shape, PATCH over PUT, standard_put, locale selection), versioned docs for the v2.0.1 and v1.4.1 tags, and the ownership verification keys for the Context7 entry.

Restructure the README usage section into task-oriented headings so
each example is self-contained: full request lines for locale
selection, a response example for ?groups[]=translations, a merge
patch example (the recommended way to edit translations, previously
the only edit example showed the PUT payload), and an explicit
full-replace PUT section. Add a limitations section covering the two
known gaps (no filtering by translated fields, one translation query
per collection item) and normalize code fence info strings.

Add context7.json so the Context7 documentation index used by AI
coding agents serves curated content: README, changelog and upgrade
guides only, usage rules stating the bundle's conventions and
footguns, versioned docs for the 1.4 and 2.0 tags, and the
verification key linking the index entry to this repository.
@paullla paullla merged commit afa92a5 into Locastic:master Jul 8, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant