dennis-koster / lighthouse-translatable
Adds translatable directive for automatic schema generation for translatable fields
Installs: 1 161
Dependents: 0
Suggesters: 0
Security: 0
Stars: 1
Watchers: 1
Forks: 0
Open Issues: 0
Requires
Requires (Dev)
- mockery/mockery: ^1.6
- orchestra/testbench: ^9
- phpunit/phpunit: ^11.3
README
This package will make generation of GraphQL types for translatable type definitions a breeze. It ships the
@translatable
directive, which can be applied to any GraphQL type definition.
The directive will look for any attributes of the TranslatableString
scalar type, also included in this package, and
include it in the types it generates.
It will respect nullable states of attributes when generating the type definitions.
The directive can generate two types of GraphQL types, based off the main type the directive gets applied to:
- A translation type: an individual type definition containing all the attributes that are translatable, along with its locale
- An input type: an input definition, containing all the attributes that are translatable, along with its locale
Installation
The package can be installed through composer.
composer require dennis-koster/lighthouse-translatable
Package compatibility
The package is completely agnostic of any translations package you might use for saving and retrieving translations to and from the database. This package focuses solely on generating schema definitions.
Its only dependency is on nuwave/lighthouse
version 6
or higher.
Arguments
The directive comes with a couple of arguments, all of them optional.
Argument | Description | Default |
---|---|---|
generateTranslationType | Whether or not to generate a type for the translation definition. | Boolean: True |
translationTypeName | The name of the type to be generated for the translation definition. | String: <BaseType>Translation |
translationsFieldName | The name of the field that holds the array of translations. | String: translations |
translationsInputName | The name of the input that holds the array of translations inputs. | String: translations |
generateInputType | Whether or not to generate a type for the translation input definition. | Boolean: True |
inputTypeName | The name of the type to be generated for the translation input definition. | String: <BaseType>TranslationInput |
appendInput | The inputs the translation model input should be appended to. | Array: [] |
The default values for the arguments may be altered through the publishable config file.
Basic usage
In its most primal form, the directive uses some sensible defaults. It will always generate a translation definition and a translation input definition for the type the directive is applied to.
It will take the name of the base type, in the example below NewsItem
and append Translation
(so NewsItemTranslation
)
for the translation definition, and TranslationInput
for the translation input definition (NewsItemTranslationInput
).
An attribute will be added to the base type definition, holding the translation definitions. By default, the attribute
will be called translations
but this is customizable through the translationsAttribute
argument.
type NewsItem @translatable { id: ID! title: TranslatableString! introduction: TranslatableString } # Will result in the following schema definition type NewsItem { id: ID! title: TranslatableString! introduction: TranslatableString translations: [NewsItemTranslation!]! # Added through the directive } type NewsItemTranslation { locale: String! title: String! introduction: String } input NewsItemTranslationInput { locale: String! title: String! introduction: String }
Append input type to existing inputs
It's possible to provide the directive an array of existing inputs you want to append a translations argument to,
through the appendInput
argument.
The attribute will be called translations
by default, and can be changed through the translationsAttribute
argument.
type NewsItem @translatable(appendInput: ["CreateNewsItemInput"]) { id: ID! slug: String! title: TranslatableString! introduction: TranslatableString } input CreateNewsItemInput { slug: String! } # Will append the translations attribute to the CreateNewsItemInput input CreateNewsItemInput { slug: String! translations: [NewsItemTranslationInput!]! }
Customize type names and attribute name
It's possible to customize the names of the type definitions that are generated, as well as the name of the attribute it appends to existing type definitions.
type NewsItem @translatable( translationTypeName: "FooBarTranslation" inputTypeName: "FooBarTranslationInput" translationsAttribute: "localizations" appendInput: ["CreateNewsItemInput"] ) { id: ID! title: TranslatableString! introduction: TranslatableString } input CreateNewsItemInput { slug: String! } # Will result in the following schema definition type NewsItem { id: ID! title: TranslatableString! introduction: TranslatableString localizations: [FooBarTranslation!]! } input CreateNewsItemInput { slug: String! localizations: [FooBarTranslationInput!]! } type FooBarTranslation { locale: String! title: String! introduction: String } input FooBarTranslationInput { locale: String! title: String! introduction: String }
Configuration
The directive comes with a configuration file that can be published through:
php artisan vendor:publish --provider=DennisKoster\\LighthouseTranslatable\\Providers\\LighthouseTranslatableProvider
Through the configuration file, all the default values for the directive may be adjusted to your liking.
View stubs
The generated types are created using blade views. These blade views can also be published and adjusted to your needs.
Blade view overview
type NewsItem @translatable(appendInput: ["CreateNewsItemInput"]) { id: ID! title: TranslatableString! introduction: TranslatableString } input CreateNewsItemInput { slug: String! } # Will result in the following schema definition type NewsItem { id: ID! title: TranslatableString! introduction: TranslatableString translations: [NewsItemTranslation!]! # translations-field.blade.php } input CreateNewsItemInput { slug: String! translations: [NewsItemTranslationInput!]! # translations-input.blade.php } type NewsItemTranslation { locale: String! # translatable-attribute-field.blade.php title: String! # translatable-attribute-field.blade.php introduction: String # translatable-attribute-field.blade.php } input NewsItemTranslationInput { locale: String! # translatable-attribute-input.blade.php title: String! # translatable-attribute-input.blade.php introduction: String # translatable-attribute-input.blade.php }