// M-Files Server gRPC API 26.11. Generated from the M-Files Server IDL; do not edit.
// Documentation: https://developer.m-files.com/APIs/gRPC-API/
syntax = "proto3";

package MFiles;

import "mfiles/api/annotations.proto";
import "mfiles/structs.proto";

option csharp_namespace = "MFiles.Grpc";
option go_package = "github.com/M-Files/mfiles-grpc-api/go/mfiles;mfiles";
option java_multiple_files = true;
option java_package = "com.mfiles.grpc";
option objc_class_prefix = "MF_";

// Adds, modifies and removes the languages of a vault, and reads and writes the translations of
// its metadata structure names.
//
// Use this interface to add, modify and delete languages in a vault.
//
// A vault has a default language (ID 0) and can have additional languages. The names of the
// metadata structure (classes, property definitions, value lists, views, workflows, named ACLs,
// ...) can be translated to each language; users see the names in their session language. M-Files
// Admin uses this service to manage the languages and translations of a vault.
//
// - **Session and rights.** Requires a vault session with the vault rights
//   `change_metadata_structure` and `license_allows_modifications`
//   ([VaultAccess](mfiles:MFiles.VaultAccess)). Reading and writing translations also needs
//   `see_all_objects`.
// - **License.** Adding and modifying languages and applying translations fail when the server's
//   license does not include the languages feature.
// - **List the languages** with [GetLanguages](mfiles:MFiles.IRPCLanguages.GetLanguages); this
//   service has no read method for them.
// - **Translate the vault:** [GetTranslations](mfiles:MFiles.IRPCLanguagesAdmin.GetTranslations)
//   with the default language as source and the target language, fill in `target_string` and
//   set `state` to `TRANSLATION_STATE_TRANSLATED`, then
//   [ApplyTranslations](mfiles:MFiles.IRPCLanguagesAdmin.ApplyTranslations).
service IRPCLanguagesAdmin {
	option (mfiles.api.service) = { book: "admin" level: LEVEL_SPECIALIZED title: "Language administration" };

	// Adds a language to the vault.
	//
	// - Requires the vault rights `change_metadata_structure` and `license_allows_modifications`, and
	//   a server license that includes the languages feature.
	// - The server assigns the ID; the value you send is ignored.
	rpc AddLanguage( AddLanguageRequest ) returns ( AddLanguageResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Changes the name or language code of a language.
	//
	// - Requires the vault rights `change_metadata_structure` and `license_allows_modifications`, and
	//   a server license that includes the languages feature.
	// - The default language (0) and additional languages can be modified; a negative ID fails with
	//   "Access denied".
	rpc ModifyLanguage( ModifyLanguageRequest ) returns ( ModifyLanguageResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Removes an additional language from the vault.
	//
	// - Deletes the language permanently. Requires the vault rights `change_metadata_structure` and
	//   `license_allows_modifications`.
	// - Only additional languages can be removed: ID 0 (the default language) or a negative ID fails
	//   with "Access denied".
	rpc RemoveLanguage( RemoveLanguageRequest ) returns ( RemoveLanguageResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets the translatable names of the vault's metadata structure, with their texts in a source and
	// a target language.
	//
	// - Requires the vault rights `change_metadata_structure`, `license_allows_modifications` and
	//   `see_all_objects`.
	// - Returns one [Translation](mfiles:MFiles.Translation) per name that exists in the default
	//   language, including the items of translatable value lists. `id` identifies the name, for
	//   example `PropertyDef_20_0_Name`; send it back unchanged in
	//   [ApplyTranslations](mfiles:MFiles.IRPCLanguagesAdmin.ApplyTranslations).
	// - If neither `include_source_language` nor `include_target_language` is true, the list is
	//   empty.
	// - `untranslated_only` filters on the target language's state, so it returns nothing unless
	//   `include_target_language` is true.
	rpc GetTranslations( GetTranslationsRequest ) returns ( GetTranslationsResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Stores translated names in a target language.
	//
	// - Requires the vault rights `change_metadata_structure`, `license_allows_modifications` and
	//   `see_all_objects`, and a server license that includes the languages feature.
	// - When at least one translation is stored, the metadata structure version changes (clients reload the
	//   names) and the vault's search indexes are marked for re-indexing.
	rpc ApplyTranslations( ApplyTranslationsRequest ) returns ( ApplyTranslationsResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}
}

// The request of AddLanguage.
message AddLanguageRequest {

	// The new language: `name` and `language_code` (for example `fi`). `id` is ignored.
	Language lang = 1;
}

// The response of AddLanguage.
message AddLanguageResponse {

	// The ID of the new language.
	int32 id = 1;
}

// The request of ModifyLanguage.
message ModifyLanguageRequest {

	// The new data of the language; `id` identifies the language.
	Language lang = 1;
}

// The response of ModifyLanguage.
message ModifyLanguageResponse {
}

// The request of RemoveLanguage.
message RemoveLanguageRequest {

	// The ID of the language to remove.
	int32 id = 1;
}

// The response of RemoveLanguage.
message RemoveLanguageResponse {
}

// The request of GetTranslations.
message GetTranslationsRequest {

	// True to fill `source_string` and `source_version`.
	bool include_source_language = 1;

	// The language of `source_string`, usually 0 (the default language). Used only with `include_source_language`.
	int32 source_language = 2;

	// True to fill `target_string` and `state`.
	bool include_target_language = 3;

	// The language being translated to. Used only with `include_target_language`.
	int32 target_language = 4;

	// True to return only names whose target text is not translated yet. Requires `include_target_language`.
	bool untranslated_only = 5;
}

// The response of GetTranslations.
message GetTranslationsResponse {

	// The translatable names. See [Translation](mfiles:MFiles.Translation).
	repeated Translation values = 1;
}

// The request of ApplyTranslations.
message ApplyTranslationsRequest {

	// The language the translations are for.
	int32 target_language = 1;

	// The translations, as returned by [GetTranslations](mfiles:MFiles.IRPCLanguagesAdmin.GetTranslations) with `target_string` and `state` filled in.
	repeated Translation ptranslations = 2;

	// True to store only the entries whose `state` is `TRANSLATION_STATE_TRANSLATED`.
	bool apply_translated_only = 3;
}

// The response of ApplyTranslations.
message ApplyTranslationsResponse {
}