How can a translation team localize Apollo Federation documentation without breaking a federated GraphQL API? This guide explains the difference between subgraphs and a supergraph, what schema composition actually checks, how entity keys and Federation 2 directives work, and why router query plans should not be simplified into promises about one backend. It is designed for readers searching for Apollo Federation 2 examples, @key and @shareable meanings, GraphQL schema composition errors, subgraph ownership or multilingual developer-documentation methods.
Federation brings several independently operated GraphQL services into a unified graph. Its appeal is organizational as well as technical: different teams can own different fields while clients query one API schema. That convenience depends on exact type names, field definitions, entity keys and directive semantics. A translated description can make these concepts understandable to an international audience; a silently renamed field or altered directive can make the graph fail composition or cause queries to resolve differently.
Imagine a global museum network. Catalogue owns exhibition records, Tickets owns admission availability, Membership owns visitor privileges and Events owns talks and workshops. A multilingual developer portal explains a single Exhibition type that draws information from more than one service. Translators must avoid claiming that one team owns every field, that a successful schema composition proves every service is healthy, or that the router’s response automatically confirms an admission purchase. We will keep the technical agreement and the reader’s interpretation aligned.
Quick answer: preserve the graph while translating its explanation
The quick answer: localize human-readable schema descriptions, usage tutorials and suitable display values; do not edit executable GraphQL type names, field names, field arguments, directive names, entity-key selections or enum tokens as part of prose translation.
Read the graph in three layers. Each subgraph has its own schema and resolvers. Composition combines compatible subgraphs into a supergraph schema containing routing metadata. The public API schema is what clients see, without internal federation machinery. These are related but not interchangeable documents.
Composition is a validity check, not a test that every distributed backend is online or that a purchase is successful. Router execution and the business state behind a field must be evaluated separately.
The most useful translated documentation connects every concept to an action: which schema a developer can query, what service resolves a field, how an entity is identified, what happens when composition fails, and which change requires coordinated release management.
What a federated museum network actually does
A federated API is a composition of independently maintained field resolvers, not a guarantee that every contributing service owns the same data, shares the same deployment cycle or uses the same language. Think of the public graph as a map of capabilities. The subgraphs maintain the capabilities, the composition machinery checks that the map fits together, and the router uses the map to retrieve data. The museum visitor sees the outcome, not the routing machinery.
How to read this guide
Start with schema layers, move to identity and directives, then study query execution, security and deployment. For every concept, ask three questions: what is declared, what runs, and what a reader may legitimately conclude? A useful translation preserves the difference between these three things and avoids making an infrastructure detail sound like a business promise.
1. Federation as a software architecture
Federation lets teams compose independent GraphQL services into a unified queryable API. The unified schema is not evidence that the underlying data has been merged into one database.
Consider a practical case. An international museum can let the Catalogue team maintain exhibitions while Tickets maintains availability; users query a unified Exhibition object. A reliable international guide should make clear which component or team has the authority to supply the relevant fact, rather than asking the reader to infer it from an English label.
The common error is not always grammatical. Translating federation as ‘complete data consolidation’ misstates data ownership and may mislead architects into assuming all data is replicated. A fluent translation can still change the architecture the reader imagines or the behavior their code expects.
For review, take a concrete verification step. Show the logical graph and the independent services separately. Use the deployment’s actual boundaries when explaining responsibility. Compare the source schema, executable example and translated explanation before considering the section finished.
2. Subgraph boundaries
A subgraph is a GraphQL API that contributes a portion of the federated schema and provides resolvers for its owned fields. Subgraph boundaries normally reflect domain ownership, not translation locales.
Consider a practical case. Membership exposes memberTier, while the Events subgraph adds nextTalk for an exhibition; neither needs to own the other’s database. A reliable international guide should make clear which component or team has the authority to supply the relevant fact, rather than asking the reader to infer it from an English label.
The common error is not always grammatical. A multilingual diagram that labels French and English websites as separate subgraphs can confuse language presentation with service architecture. A fluent translation can still change the architecture the reader imagines or the behavior their code expects.
For review, take a concrete verification step. Identify subgraphs from the published graph configuration, not from the number of languages or frontend pages. Compare the source schema, executable example and translated explanation before considering the section finished.
3. Supergraph schema
The supergraph schema is the composed artifact that includes both public schema information and internal federation information used for query planning and routing.
Consider a practical case. The deployment composes Catalogue, Membership and Tickets into one supergraph before a router accepts exhibition queries. A reliable international guide should make clear which component or team has the authority to supply the relevant fact, rather than asking the reader to infer it from an English label.
The common error is not always grammatical. Calling the supergraph a simple glossary or a schema drawn manually by translators hides the role of composition and routing metadata. A fluent translation can still change the architecture the reader imagines or the behavior their code expects.
For review, take a concrete verification step. Treat the supergraph as generated technical output. Translate associated explanations, not its machine-readable definitions. Compare the source schema, executable example and translated explanation before considering the section finished.
4. Public API schema
The API schema represents the client-visible GraphQL contract and omits federation-specific machinery that belongs to the supergraph implementation.
Consider a practical case. A third-party mobile app can query Exhibition.title and Exhibition.availability without knowing the internal @join metadata. A reliable international guide should make clear which component or team has the authority to supply the relevant fact, rather than asking the reader to infer it from an English label.
The common error is not always grammatical. Publishing internal query-planner directives as if clients must invoke them creates confusion and can leak irrelevant implementation details. A fluent translation can still change the architecture the reader imagines or the behavior their code expects.
For review, take a concrete verification step. Use the public API schema for consumer-facing examples, and document internal machinery only for the teams responsible for it. Compare the source schema, executable example and translated explanation before considering the section finished.
5. Composition versus deployment
Schema composition validates whether subgraph definitions can combine under federation rules. It does not by itself deploy services or prove that all resolvers work.
Consider a practical case. Catalogue releases a new description field; composition succeeds even though a backend deployment has not reached the router environment. A reliable international guide should make clear which component or team has the authority to supply the relevant fact, rather than asking the reader to infer it from an English label.
The common error is not always grammatical. A translated release note that equates ‘composed successfully’ with ‘available to every user now’ invents operational certainty. A fluent translation can still change the architecture the reader imagines or the behavior their code expects.
For review, take a concrete verification step. Separate schema registry publication, supergraph distribution, router activation and real application tests in documentation. Compare the source schema, executable example and translated explanation before considering the section finished.
6. Breaking composition
Incompatible field definitions or unmet federation rules can prevent composition. The failure protects a router from receiving an inconsistent new supergraph.
Consider a practical case. One subgraph defines admissionPrice as Int while another defines the same shared field as String, creating a conflict. A reliable international guide should make clear which component or team has the authority to supply the relevant fact, rather than asking the reader to infer it from an English label.
The common error is not always grammatical. The misleading translation ‘composition warning’ may understate a build-blocking incompatibility that requires engineering attention. A fluent translation can still change the architecture the reader imagines or the behavior their code expects.
For review, take a concrete verification step. Retain the exact error and implicated types, and explain the resolution using the official composition rule rather than a guessed fix. Compare the source schema, executable example and translated explanation before considering the section finished.
7. The @link directive
Federation 2 subgraphs use @link to import federation specification definitions and directives; the referenced specification version is not an editorial document version.
Consider a practical case. A museum schema imports @key and @shareable from a federation specification URL so composition can interpret their meanings. A reliable international guide should make clear which component or team has the authority to supply the relevant fact, rather than asking the reader to infer it from an English label.
The common error is not always grammatical. Translating an @link URL, import token or version number as visible copy changes how the schema is interpreted. A fluent translation can still change the architecture the reader imagines or the behavior their code expects.
For review, take a concrete verification step. Preserve the directive declaration and check the compatible router and composition tool versions before publishing samples. Compare the source schema, executable example and translated explanation before considering the section finished.
8. Entity identification with @key
The @key directive identifies one or more fields through which an entity can be referred to across subgraphs. It is part of the service’s data identity contract.
Consider a practical case. Exhibition @key(fields: "id") permits Tickets to contribute availability for the Exhibition identified by its stable ID. A reliable international guide should make clear which component or team has the authority to supply the relevant fact, rather than asking the reader to infer it from an English label.
The common error is not always grammatical. Translating the key selection’s field name because ‘id’ sounds unnatural breaks entity reference resolution. A fluent translation can still change the architecture the reader imagines or the behavior their code expects.
For review, take a concrete verification step. Explain the identity in natural language while retaining the exact key field selection string and identifier format. Compare the source schema, executable example and translated explanation before considering the section finished.
9. Multiple entity keys
An entity can have more than one supported key under relevant federation definitions, but the keys must be usable consistently by the services involved.
Consider a practical case. Catalogue recognizes an internal exhibition ID and a partner accession code, while Tickets resolves only the supported representation it receives. A reliable international guide should make clear which component or team has the authority to supply the relevant fact, rather than asking the reader to infer it from an English label.
The common error is not always grammatical. Assuming every arbitrary alternative key is universally accepted may produce missing references or failed entity fetches. A fluent translation can still change the architecture the reader imagines or the behavior their code expects.
For review, take a concrete verification step. Document the keys each subgraph supports and test the actual entity representations passed through router operations. Compare the source schema, executable example and translated explanation before considering the section finished.
10. Entity representations
Federation entity resolution can pass representations that identify an object, including typename and key fields, between subgraphs. These are machine-level structures, not translated biographies.
Consider a practical case. A router needs an Exhibition representation with __typename and id to ask Tickets for its availability field. A reliable international guide should make clear which component or team has the authority to supply the relevant fact, rather than asking the reader to infer it from an English label.
The common error is not always grammatical. Editing __typename, changing a key or substituting a localized display title as an identifier makes cross-subgraph resolution unreliable. A fluent translation can still change the architecture the reader imagines or the behavior their code expects.
For review, take a concrete verification step. Treat representation examples as executable contract samples; translate surrounding prose while keeping identifiers exact. Compare the source schema, executable example and translated explanation before considering the section finished.
11. The role of entity resolvers
A subgraph may resolve an entity from key information using implementation-specific resolvers. The existence of an entity key does not guarantee that every real record exists.
Consider a practical case. Tickets receives an exhibition ID and checks its own admission database before providing available slots. A reliable international guide should make clear which component or team has the authority to supply the relevant fact, rather than asking the reader to infer it from an English label.
The common error is not always grammatical. A guide that equates a well-formed key with a guaranteed record encourages readers to misinterpret nulls or lookup errors. A fluent translation can still change the architecture the reader imagines or the behavior their code expects.
For review, take a concrete verification step. Describe the possible absent-record behavior and the source that establishes authoritative business state. Compare the source schema, executable example and translated explanation before considering the section finished.
12. @external fields
The @external directive marks fields used in a subgraph definition that are normally resolved elsewhere, often in coordination with @requires or @provides. Its precise behavior depends on federation semantics.
Consider a practical case. Tickets refers to Catalogue’s Exhibition.capacity when computing reservation guidance under a documented cross-subgraph dependency. A reliable international guide should make clear which component or team has the authority to supply the relevant fact, rather than asking the reader to infer it from an English label.
The common error is not always grammatical. Calling external fields ‘external websites’ falsely shifts the meaning from resolver ownership to an internet boundary. A fluent translation can still change the architecture the reader imagines or the behavior their code expects.
For review, take a concrete verification step. Identify the owning field and the dependency, and keep @external syntax unchanged in every localized schema sample. Compare the source schema, executable example and translated explanation before considering the section finished.
13. @requires dependencies
The @requires directive declares that resolving a field needs specified external fields. It affects query planning and cannot be replaced with a plain text statement of preference.
Consider a practical case. An eligibility field needs a membershipTier and eventCategory before its resolver can evaluate museum access. A reliable international guide should make clear which component or team has the authority to supply the relevant fact, rather than asking the reader to infer it from an English label.
The common error is not always grammatical. A translation that makes the requirement optional or changes its field-set string can misrepresent the resolver’s prerequisites. A fluent translation can still change the architecture the reader imagines or the behavior their code expects.
For review, take a concrete verification step. Show the prerequisite fields with their exact names and explain why the router must acquire them. Compare the source schema, executable example and translated explanation before considering the section finished.
14. @provides optimization
The @provides directive indicates that a resolver can provide particular fields of a returned entity in that context. It can reduce other fetches under relevant conditions.
Consider a practical case. A Recommendations service returns featured exhibitions with a title already available as part of the same resolver context. A reliable international guide should make clear which component or team has the authority to supply the relevant fact, rather than asking the reader to infer it from an English label.
The common error is not always grammatical. Translating provides as ‘owns every field permanently’ confuses contextual capability with general ownership. A fluent translation can still change the architecture the reader imagines or the behavior their code expects.
For review, take a concrete verification step. Check the documented field-set and context; do not imply all queries or all subgraphs have the same optimization. Compare the source schema, executable example and translated explanation before considering the section finished.
15. @shareable and consistent results
A field marked @shareable may be resolved from multiple subgraphs if composition requirements are satisfied. The services should return compatible values, not merely compatible types.
Consider a practical case. Catalogue and Search both expose an Exhibition.slug; their values must agree if a router may use either source. A reliable international guide should make clear which component or team has the authority to supply the relevant fact, rather than asking the reader to infer it from an English label.
The common error is not always grammatical. Calling shareable ‘translated freely by every team’ risks inconsistent business data and client-visible surprises. A fluent translation can still change the architecture the reader imagines or the behavior their code expects.
For review, take a concrete verification step. Keep the directive token exact and evaluate shared resolver behavior, not only SDL syntax. Compare the source schema, executable example and translated explanation before considering the section finished.
16. @override and controlled ownership migration
The @override directive supports shifting resolution of a field between subgraphs under federation rules; it is not a generic instruction to overwrite a translation.
Consider a practical case. A team migrates exhibition rating from Reviews to Catalogue and tracks which subgraph should resolve the field during rollout. A reliable international guide should make clear which component or team has the authority to supply the relevant fact, rather than asking the reader to infer it from an English label.
The common error is not always grammatical. A translated note that says both services always serve the field simultaneously masks migration and routing choices. A fluent translation can still change the architecture the reader imagines or the behavior their code expects.
For review, take a concrete verification step. Document source and target subgraphs, composition checks and rollout controls for the federation version actually deployed. Compare the source schema, executable example and translated explanation before considering the section finished.
17. @inaccessible and public visibility
The @inaccessible directive can keep certain schema elements available to composition while hiding them from the client-facing API schema.
Consider a practical case. An internal ticket reconciliation field supports cross-service definitions without being made queryable to public clients. A reliable international guide should make clear which component or team has the authority to supply the relevant fact, rather than asking the reader to infer it from an English label.
The common error is not always grammatical. Rendering the field in a customer tutorial because it appears in internal SDL can advertise functionality clients cannot access. A fluent translation can still change the architecture the reader imagines or the behavior their code expects.
For review, take a concrete verification step. Compare API schema output to internal subgraph definitions and avoid promising private fields to consumers. Compare the source schema, executable example and translated explanation before considering the section finished.
18. Field ownership and team responsibility
A federated type may aggregate fields from several services. Type-level visibility does not imply one team owns all fields or controls every downstream data source.
Consider a practical case. An Exhibition page shows curatorial text, ticket availability and a membership discount contributed by distinct owners. A reliable international guide should make clear which component or team has the authority to supply the relevant fact, rather than asking the reader to infer it from an English label.
The common error is not always grammatical. Explaining ‘Exhibition belongs to Tickets’ as a whole erases Catalogue’s authority over published descriptions. A fluent translation can still change the architecture the reader imagines or the behavior their code expects.
For review, take a concrete verification step. Attach ownership to fields and resolvers where relevant and route corrections to the correct team. Compare the source schema, executable example and translated explanation before considering the section finished.
19. GraphQL type names and field names
GraphQL SDL type identifiers and field identifiers are executable contract names. Multilingual reader labels can explain them, but changing SDL names requires a deliberate API change.
Consider a practical case. The API field startAt remains startAt in source code while the web interface displays a localized time label. A reliable international guide should make clear which component or team has the authority to supply the relevant fact, rather than asking the reader to infer it from an English label.
The common error is not always grammatical. Translating startAt to a language-specific key in a code block causes client queries to fail validation. A fluent translation can still change the architecture the reader imagines or the behavior their code expects.
For review, take a concrete verification step. Maintain a glossary pairing canonical tokens with reader-facing explanations, and compile every revised query sample. Compare the source schema, executable example and translated explanation before considering the section finished.
20. Nullability and promises
A GraphQL Non-Null marker affects the field’s response contract and error propagation. It should never be treated as mere punctuation in a translated technical guide.
Consider a practical case. An Exhibition.title declared String! has different null-handling expectations from optional admissionNotes. A reliable international guide should make clear which component or team has the authority to supply the relevant fact, rather than asking the reader to infer it from an English label.
The common error is not always grammatical. Dropping the exclamation mark in a copied example changes the schema and can hide a breaking contract revision. A fluent translation can still change the architecture the reader imagines or the behavior their code expects.
For review, take a concrete verification step. Review non-null and list modifiers character for character, then describe what failures mean for actual client responses. Compare the source schema, executable example and translated explanation before considering the section finished.
21. Arguments and default values
Arguments constrain how a field is invoked, including types, nullability and defaults. A localized parameter description must remain consistent with the declared schema.
Consider a practical case. The field exhibitions(first: Int = 10) may default to ten items; a display label cannot turn that into an unbounded result. A reliable international guide should make clear which component or team has the authority to supply the relevant fact, rather than asking the reader to infer it from an English label.
The common error is not always grammatical. Changing a default value to match a translated sentence can affect client workload and pagination expectations. A fluent translation can still change the architecture the reader imagines or the behavior their code expects.
For review, take a concrete verification step. Compare SDL defaults and sample queries, and document which values are client-selected versus server-defined. Compare the source schema, executable example and translated explanation before considering the section finished.
22. Enums across locales
GraphQL enum values are machine-readable alternatives. Their stable tokens can map to localized labels without being renamed in the schema.
Consider a practical case. AdmissionStatus has AVAILABLE and SOLD_OUT, while a ticket app displays the relevant translation to visitors. A reliable international guide should make clear which component or team has the authority to supply the relevant fact, rather than asking the reader to infer it from an English label.
The common error is not always grammatical. A translated enum literal will not match the schema unless the API truly defines that literal. A fluent translation can still change the architecture the reader imagines or the behavior their code expects.
For review, take a concrete verification step. Put language-specific labels in a presentation layer and keep query variables and enum literals intact. Compare the source schema, executable example and translated explanation before considering the section finished.
23. Interfaces and possible types
An interface defines fields implemented by object types. Federation can involve abstract types and cross-service implementations, but exact composition rules must be checked.
Consider a practical case. A MuseumContent interface is implemented by Exhibition and CollectionItem with different resolvers and type-specific fields. A reliable international guide should make clear which component or team has the authority to supply the relevant fact, rather than asking the reader to infer it from an English label.
The common error is not always grammatical. Explaining an interface as ‘a page design’ can misdirect readers from schema contracts to frontend templates. A fluent translation can still change the architecture the reader imagines or the behavior their code expects.
For review, take a concrete verification step. Document implemented types and query fragments; test __typename and possible-type behavior with supported clients. Compare the source schema, executable example and translated explanation before considering the section finished.
24. Query planning and fetch ordering
A federated router determines how to obtain requested fields from relevant subgraphs, using the composed graph. The plan is not always a single backend request.
Consider a practical case. One client query needs an Exhibition from Catalogue followed by ticket slots from Tickets, possibly with other independent fetches. A reliable international guide should make clear which component or team has the authority to supply the relevant fact, rather than asking the reader to infer it from an English label.
The common error is not always grammatical. A diagram that says all subgraphs answer instantly or in parallel makes unsupported latency and sequencing promises. A fluent translation can still change the architecture the reader imagines or the behavior their code expects.
For review, take a concrete verification step. Explain dependencies where they matter, distinguishing conceptual field access from observed execution performance. Compare the source schema, executable example and translated explanation before considering the section finished.
25. Partial data and GraphQL errors
A federated query may return partial data along with GraphQL errors depending on failure and nullability semantics. A simple ‘success/failure’ label can erase this nuance.
Consider a practical case. An exhibition description appears while ticket availability fails because the Tickets service is unavailable. A reliable international guide should make clear which component or team has the authority to supply the relevant fact, rather than asking the reader to infer it from an English label.
The common error is not always grammatical. Promising that the entire page is either complete or absent may mislead clients handling partial results. A fluent translation can still change the architecture the reader imagines or the behavior their code expects.
For review, take a concrete verification step. Show data and errors in the same example and explain what the client may safely display or retry. Compare the source schema, executable example and translated explanation before considering the section finished.
26. Authorization is not centralized automatically
Federation does not, by itself, guarantee that subgraph permissions are coherent. Gateways and services need an explicit security model.
Consider a practical case. A public exhibition field is readable anonymously, while membership discounts require an authenticated visitor with suitable privileges. A reliable international guide should make clear which component or team has the authority to supply the relevant fact, rather than asking the reader to infer it from an English label.
The common error is not always grammatical. Treating a single router entry point as proof that every resolver enforces policy risks access-control gaps. A fluent translation can still change the architecture the reader imagines or the behavior their code expects.
For review, take a concrete verification step. Explain which layer authorizes each field and how identity or scopes reach subgraphs without leaking secrets. Compare the source schema, executable example and translated explanation before considering the section finished.
27. Schema checks and breaking changes
Teams should evaluate changes against the composed graph and affected client operations, not only against an isolated subgraph’s SDL.
Consider a practical case. Tickets removes a field that a museum kiosk query still uses; local compilation might pass while client operations break. A reliable international guide should make clear which component or team has the authority to supply the relevant fact, rather than asking the reader to infer it from an English label.
The common error is not always grammatical. Translating ‘backward-compatible locally’ as ‘safe for all clients’ hides federated dependency risk. A fluent translation can still change the architecture the reader imagines or the behavior their code expects.
For review, take a concrete verification step. Run composition and operation checks against the intended graph version, and name the consumers affected by removals. Compare the source schema, executable example and translated explanation before considering the section finished.
28. Contract variants and scoped exposure
Some managed graph platforms support contract variants that expose selected portions of a graph. Their configuration is not a multilingual translation layer by default.
Consider a practical case. A partner API includes event descriptions but excludes internal membership eligibility fields under a separately managed contract. A reliable international guide should make clear which component or team has the authority to supply the relevant fact, rather than asking the reader to infer it from an English label.
The common error is not always grammatical. A guide that equates language locale with access contract can confuse presentation preference with security and schema filtering. A fluent translation can still change the architecture the reader imagines or the behavior their code expects.
For review, take a concrete verification step. Clarify which variant a client queries, why fields are available and which language-specific descriptions accompany them. Compare the source schema, executable example and translated explanation before considering the section finished.
29. Schema registration and publication
Publishing subgraph definitions to a registry can initiate composition and distribution workflows. Those workflows depend on product configuration and do not guarantee immediate client adoption.
Consider a practical case. A museum registers a new Events schema, then checks composition before a router fetches the updated supergraph. A reliable international guide should make clear which component or team has the authority to supply the relevant fact, rather than asking the reader to infer it from an English label.
The common error is not always grammatical. Saying ‘uploaded means live everywhere’ can obscure failed checks or delayed distribution. A fluent translation can still change the architecture the reader imagines or the behavior their code expects.
For review, take a concrete verification step. List registry acceptance, composition result, router update and consumer testing as distinct verified milestones. Compare the source schema, executable example and translated explanation before considering the section finished.
30. Deprecation notices
GraphQL can mark fields or enum values deprecated with reason text. The reason is human-readable but still important guidance for client migration.
Consider a practical case. A legacy admissionPrice field remains available temporarily while a new priceBreakdown field is introduced. A reliable international guide should make clear which component or team has the authority to supply the relevant fact, rather than asking the reader to infer it from an English label.
The common error is not always grammatical. Deleting a deprecation warning because it looks redundant can strand international clients on obsolete fields. A fluent translation can still change the architecture the reader imagines or the behavior their code expects.
For review, take a concrete verification step. Preserve the deprecated token and version commitments; localize the reason and migration instructions accurately. Compare the source schema, executable example and translated explanation before considering the section finished.
31. Operational monitoring
Subgraph health, router request metrics, errors and latency reveal runtime behavior but are separate from schema composition validity.
Consider a practical case. The router successfully composes a graph while Tickets displays elevated timeouts during a ticket sale. A reliable international guide should make clear which component or team has the authority to supply the relevant fact, rather than asking the reader to infer it from an English label.
The common error is not always grammatical. Calling the graph ‘healthy’ solely because composition passed hides the real customer experience. A fluent translation can still change the architecture the reader imagines or the behavior their code expects.
For review, take a concrete verification step. Describe which dashboard measures schema, router or business behavior and avoid translating metric names used as stable keys. Compare the source schema, executable example and translated explanation before considering the section finished.
32. Localization QA with executable operations
The strongest multilingual review validates representative queries against the schema and has target-language reviewers predict their meaning.
Consider a practical case. A reviewer runs exhibition search, membership discount and ticket availability queries in a staging graph. A reliable international guide should make clear which component or team has the authority to supply the relevant fact, rather than asking the reader to infer it from an English label.
The common error is not always grammatical. A prose-only review may miss a field rename hidden in an example or a claim that a resolver guarantees purchase completion. A fluent translation can still change the architecture the reader imagines or the behavior their code expects.
For review, take a concrete verification step. Keep test cases for each subgraph dependency and use only fictional public examples when writing consumer-facing documentation. Compare the source schema, executable example and translated explanation before considering the section finished.
End-to-end example: catalogue, tickets, membership and one graph
Worked scenario, first request. A mobile museum guide queries Exhibition.title and Exhibition.location. Catalogue resolves both fields. A localized API reference may describe title as the public exhibition title, but should not translate the identifier inside the query or promise a translated title is available for every language. That latter behavior depends on the data model and locale arguments actually implemented.
Second request. The mobile guide asks for Exhibition.availableSlots. Tickets resolves the field for an entity identified through its agreed key. The router may fetch prerequisite data from Catalogue, then request the field from Tickets. Translate the dependency clearly but do not imply that the mobile app calls Tickets directly or that a composable schema implies a particular query plan for every query.
Third request. The guide asks for a member discount. Membership requires appropriate identity and membership conditions. The statement ‘this field exists’ does not tell the visitor whether a discount is owed. The localization should explain the authorization boundary, the possible not-eligible result and the official business process for confirming a benefit.
Fourth request. Catalogue changes Exhibition.title from String! to String in its local schema. Even when the English release note is friendly, this can alter the public client’s nullability expectations and interact with other subgraphs. A correct international guide identifies the change as a contract issue that requires composition and client checks, not an innocent punctuation edit.
Fifth request. The network deploys the new supergraph, but one subgraph goes offline. The router may return errors and perhaps partial data. A translator must not treat the earlier composition success message as evidence of runtime availability. The correct operational account names which layer was validated, which layer failed and which data may still be safe to show.
A useful release checklist
Begin with a diff of schema tokens, fields, arguments, directive names, key selections and enum values. When translation is the only approved change, the machine-contract diff should be empty. Run schema composition for the intended Federation version, then test representative operations against the expected graph. Check documentation labels independently of actual field names.
Ask a target-language developer to explain which subgraph owns the data, how the entity is connected, how errors and partial responses are handled, and whether a recorded business action has actually happened. Evaluate whether any statement implies an unverified security, latency or availability guarantee. Record which deployment and schema version each example was checked against.
Frequently asked questions
Is a supergraph the same as the public API schema?
No. The composed supergraph includes federation routing information; the API schema describes the client-visible contract.
May translators rename @key fields?
No. Field-set selections and identifiers are executable elements. Localize their descriptions separately.
Does @shareable mean different teams may return different values?
It permits compatible multi-subgraph resolution, but divergent values can cause inconsistent client responses.
Can composition success prove that every service is available?
No. Composition checks schema compatibility; runtime health and business correctness require separate evidence.
Does @override authorize a translation override?
No. It is a federation directive affecting field resolution ownership.
Can a query return partial data when one subgraph fails?
Depending on GraphQL error and nullability behavior, yes. Client guidance should reflect that possibility.
Should developer samples be translated line by line?
Translate explanatory prose, then validate executable schema and query tokens without changing them.
How do I check the right Federation version?
Read the subgraph @link specification import and the deployed composition/router tool versions, then use matching official documentation.
What is the ultimate acceptance test?
The translated page should let a developer write a valid query and interpret field ownership, composition errors and runtime results correctly.
Official documentation and further reading
Apollo Federation overview: https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/federation . Schema composition: https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/composition . Federation directives: https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/reference/directives . GraphQL federation concepts: https://graphql.org/learn/federation/ . Check the exact federation spec and tool versions in your project rather than assuming all features have universal semantics.
Conclusion
Professional localization of a federated GraphQL API turns a complicated distributed agreement into an understandable one without changing that agreement. The reader should recognize which fields are public, which services resolve them, what composition validates and what real runtime behavior remains uncertain. Translate the guidance generously; preserve the executable graph exactly.