How vtex-apps/admin-catalog-translations works
Project Type and Purpose
• This is a full-stack VTEX IO admin application called “Admin Catalog Translation.”
• Purpose: Provide UI pages to list, export, import and edit SEO-relevant translations for catalog entities (Category, Product, SKU, Brand, Specification, Collection) across multiple storefront bindings in a VTEX account.
File-Structure Analysis
• Top-level:
• manifest.json, service.json, package.json – VTEX IO app manifests and dependency declarations
• .vtexignore, CI config, lint/prettier rules, docs, CHANGELOG
• admin/ – JSON definitions for VTEX IO Admin App navigation and route registration
• node/ – The backend service:
• clients/ – modules wrapping external VTEX GraphQL endpoints (e.g. catalog, catalogGQL)
• resolvers/ – one folder per entity (brand, category, product, sku, collection, field, translation) defining GraphQL resolvers for queries & mutations (.upload.ts, index.ts)
• utils/ – shared helper functions
• react/ – The frontend:
• components/ – per-entity translation pages (forms, import/export modals), plus shared UI (buttons, modal, error handlers, locale selector)
• graphql/ – .gql queries and mutations used by the components
• hooks/, providers/, utils/ – custom React hooks, context providers (alerts), file parsers, sanitation logic
• BrandTranslation.tsx, CategoryTranslation.tsx, etc. – top-level screens
• messages/ & public/metadata – localization resource files for multiple languages
• docs/ – developer documentation
Key Architecture Insights from README
• Uses VTEX IO CLI for installation
• Talks to vtex.catalog-graphql rather than the messages app to focus on SEO fields
• Each entity page lists storefront bindings; default binding is read-only; other bindings support create/update via GraphQL
• Bulk import/export via CSV/JSON files
a. Main Components
1. Admin UI (React App)
2. VTEX IO GraphQL Gateway (managed by VTEX platform)
3. Node Service (GraphQL resolvers)
4. External VTEX Catalog GraphQL API (vtex.catalog-graphql)
5. Static Assets & Localization (public/metadata + messages)
b. Relationships & Data Flows
• User interacts with React UI in the Admin Console.
• React components invoke GraphQL operations against the VTEX IO GraphQL Gateway.
• Gateway routes queries/mutations to the Node Service.
• Node Service resolvers use internal clients to call the external vtex.catalog-graphql API for read/write on catalog data.
• Node Service returns data back through the gateway to the UI.
• Bulk import/export flows: UI → Node (uploads file) → Node processes & calls external API → returns status.
c. Architectural Patterns & Principles
• Full-stack separation (UI vs. service)
• Schema-first GraphQL API (schema.graphql + resolvers)
• Single responsibility per resolver folder (one entity-per-module)
• Reusable client wrappers for external GraphQL calls
• i18n using JSON resource bundles for static text and for data translations
d. Technologies & Frameworks
• Frontend: React, TypeScript, VTEX Styleguide components, GraphQL (Apollo or fetch), custom hooks & context
• Backend: Node.js (TypeScript), VTEX IO service.json, GraphQL resolvers
• Deployment & Hosting: VTEX IO platform
• Data: External VTEX Catalog GraphQL service