phrase

package
v0.0.0-...-e13964f Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jan 31, 2018 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package phrase provides a client for using the PhraseApp API.

Construct a new API client, then use the various services on the client to access different parts of the PhraseApp API. For example:

client := phrase.New(token)

// list all the locales in the current project
locales, err := client.Locales.ListAll()

The services of a client correspond to the structure of the PhraseApp API documentation at http://docs.phraseapp.com/api/v1/.

Authentication

The client object sends the authentication token (obtained from your project overview page in Phrase) for all API requests, but some requests require that you perform a user login before it can be performed. These requests are marked as signed requests in the documentation. To do a user login, use the sessions service:

userAuthToken, err := client.Sessions.Create(email, password)

The userAuthToken can now be used to create a new PhraseApp client that can be used to do signed API requests:

newClient, err := phrase.NewClient(userAuthToken, token, nil)

For more information on authentication, see http://docs.phraseapp.com/api/v1/authentication/

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CheckResponse

func CheckResponse(r *http.Response) error

CheckResponse checks the API response for errors, and returns them if present. A response is considered an error if it has a status code outside the 200 range.

Types

type BlacklistService

type BlacklistService struct {
	// contains filtered or unexported fields
}

BlacklistService provides access to the blacklist related functions in the PhraseApp API.

PhraseApp API docs: http://docs.phraseapp.com/api/v1/blacklisted_keys/

func (*BlacklistService) Keys

func (s *BlacklistService) Keys() ([]string, error)

Keys lists all blacklisted keys.

PhraseApp API docs: http://docs.phraseapp.com/api/v1/blacklisted_keys/

type Client

type Client struct {
	BaseURL   *url.URL
	UserAgent string

	// Authentication token that is required for all API requests.
	// It can either be the the project authentication token, or
	// in the case of signed requests, the user authentication token,
	// in which case the ProjectAuthToken should contain the project
	// authentication token.
	AuthToken string

	// Project authentication token which is only required when AuthToken
	// contains the user auth token which is required in signed requests.
	ProjectAuthToken string

	// Services used for talking to different parts of the PhraseApp API.
	Sessions     *SessionsService
	Projects     *ProjectsService
	Locales      *LocalesService
	Keys         *KeysService
	Blacklist    *BlacklistService
	Tags         *TagsService
	Translations *TranslationsService
	FileImports  *FileImportsService
	Orders       *OrdersService
	// contains filtered or unexported fields
}

A Client manages communication with the PhraseApp API.

func New

func New(authtoken string) *Client

New creates a Phrase API client. To use API methods that require user credentials (i.e. signed requests), use NewClient.

func NewClient

func NewClient(authToken, projectToken string, httpClient *http.Client) *Client

NewClient returns a PhraseApp API client. If a nil httpClient is provided, http.DefaultClient will be used. NewClient allows the setting of AuthToken and ProjectAuthToken, unlike New.

func (*Client) Do

func (c *Client) Do(req *http.Request, v interface{}) (*http.Response, error)

Do sends an API request and returns the API response. The API response is JSON decoded and stored in the value pointed to by v, or returned as an error if an API error has occurred. If v implements the io.Writer interface, the raw response body will be written to v, without attempting to first decode it.

func (*Client) NewRequest

func (c *Client) NewRequest(method, urlStr string, params url.Values) (*http.Request, error)

NewRequest creates an API request. A relative URL can be provided in urlStr, in which case it is resolved relative to the BaseURL of the Client. Relative URLs should always be specified without a preceding slash. Params are added as query strings for GET requests, and url encoded for others.

func (*Client) NewUploadRequest

func (c *Client) NewUploadRequest(urlStr string, params url.Values, paramName, filename string, reader io.Reader) (*http.Request, error)

NewUploadRequest creates an upload request.

type DownloadRequest

type DownloadRequest struct {
	// Name of the locale that should be downloaded. This field is mandatory.
	Locale string `url:"locale"`

	// Name of the format that should be downloaded. This field is mandatory.
	// http://docs.phraseapp.com/guides/formats/
	Format string `url:"format"`

	// Encoding of the downloaded file
	Encoding string `url:"encoding,omitempty"`

	// Date since the last update. Only return translations that were modified after the given date.
	UpdatedSince time.Time `url:"updated_since,omitempty"`
	Tag          string    `url:"tag,omitempty"`

	// Include empty translations in the result as well.
	IncludeEmptyTranslations bool `url:"include_empty_translations,int,omitempty"`

	// Do not remove NOTRANSLATE tags in the downloaded translations.
	KeepNotranslateTags bool `url:"keep_notranslate_tags,int,omitempty"`

	// Enable Emoji conversion.
	ConvertEmoji bool `url:"convert_emoji,int,omitempty"`

	// Skip unverified translations from appearing in the downloaded file.
	SkipUnverifiedTranslations bool `url:"skip_unverified_translations,int,omitempty"`
}

DownloadRequest represents the parameters to the download API call.

type ErrorResponse

type ErrorResponse struct {
	*http.Response

	ErrorRaw    json.RawMessage `json:"error"`
	MessagesRaw json.RawMessage `json:"messages"`

	// Message represents the error message.
	Message string `json:"-"`

	// ValidationError represents validation errors pertaining to the request, containing a map of field to error message.
	ValidationError errorMap `json:"-"`
}

ErrorResponse represents the response when the PhraseApp API returns an error. Error responses are expected to have either a text message (stored in the Message field), or a map of string arrays (stored in ValidationError).

func ResponseError

func ResponseError(resp *http.Response) *ErrorResponse

ResponseError returns a populated ErrorResponse from an *http.Response.

func (*ErrorResponse) Error

func (r *ErrorResponse) Error() string

type FileImportRequest

type FileImportRequest struct {
	Locale   string `url:"file_import[locale_code]"`
	Filename string `url:"file_import[filename],omitempty"`

	// http://docs.phraseapp.com/guides/formats/
	Format string   `url:"file_import[format],omitempty"`
	Tags   []string `url:"file_import[tag_names],comma,omitempty"`

	// Force the update of all translations with the file content.
	UpdateTranslations bool `url:"file_import[update_translations],int,omitempty"`

	// Do not initiate verification process for existing translations when updating translations.
	SkipUnverification bool `url:"file_import[skip_unverification],int,omitempty"`

	// Prevent creating an upload tag automatically.
	SkipUploadTags bool `url:"file_import[skip_upload_tags],int,omitempty"`

	// Enable Emoji conversion.
	ConvertEmoji bool `url:"file_import[convert_emoji],int,omitempty"`

	// Some formats can have additional options. Please check the format guide for more information about available options.
	FormatOptions formatOptions `url:"file_import[format_options],omitempty"`
}

FileImportRequest represents a file upload request.

type FileImportsService

type FileImportsService struct {
	// contains filtered or unexported fields
}

FileImportsService provides access to the file upload service in the PhraseApp API.

PhraseApp API docs: http://docs.phraseapp.com/api/v1/file_imports/

func (*FileImportsService) Upload

func (s *FileImportsService) Upload(i *FileImportRequest, reader io.Reader) error

Upload a localization file.

PhraseApp API docs: http://docs.phraseapp.com/api/v1/file_imports/

type Key

type Key struct {
	ID int `json:"id" url:",omitempty"`

	// Name of the key. This is the only required field.
	Name string `json:"name" url:"translation_key[name]"`

	// Plural name of the key, e.g. for use in Gettext format.
	NamePlural  string `json:"name_plural" url:"translation_key[name_plural],omitempty"`
	Description string `json:"description" url:"translation_key[description]"`
	Pluralized  bool   `json:"pluralized" url:"translation_key[pluralized],int,omitempty"`

	// Data type of the key. The values can be string, number, boolean, or array
	DataType string   `json:"data_type" url:"translation_key[data_type],omitempty"`
	Tags     []string `json:"tag_list" url:"translation_key[tag_names],comma"`

	// Mark key as unformatted.
	Unformatted bool `json:"unformatted" url:"translation_key[unformatted],int,omitempty"`

	// Mark xml:space="preserve" as true, i.e. for Android XML format.
	MaxCharacters int `json:"max_characters_allowed" url:"translation_key[max_characters_allowed]"`

	// Max. number of characters for this key, default is 0 (unlimited).
	XMLSpacePreserve bool `json:"xml_space_preserve" url:"translation_key[xml_space_preserve],int,omitempty"`
}

Key represents a translation key.

type KeyTranslation

type KeyTranslation struct {
	String string
	Map    map[string]string
}

KeyTranslation represents a response from the Translate API call. The response can be either a String or a Map, which are stored in the appropriate fields.

type KeysService

type KeysService struct {
	// contains filtered or unexported fields
}

KeysService provides access to the translation key related functions in the PhraseApp API.

PhraseApp API docs: http://docs.phraseapp.com/api/v1/translation_keys/

func (*KeysService) Create

func (s *KeysService) Create(k *Key) (*Key, error)

Create a new key for the current project. This is a signed request.

PhraseApp API docs: http://docs.phraseapp.com/api/v1/translation_keys/#create

func (*KeysService) Destroy

func (s *KeysService) Destroy(id int) error

Destroy key identified by id. Be careful: This will delete all associated translations as well! This is a signed request.

PhraseApp API docs: http://docs.phraseapp.com/api/v1/translation_keys/#destroy

func (*KeysService) DestroyMultiple

func (s *KeysService) DestroyMultiple(ids []int) error

DestroyMultiple deletes multiple keys identified by their ids. Be careful: This will delete all associated translations as well! The number of keys to delete is limited to 50 per request. This is a signed request.

PhraseApp API docs: http://docs.phraseapp.com/api/v1/translation_keys/#destroy_multiple

func (*KeysService) Get

func (s *KeysService) Get(keyNames []string) ([]Key, error)

Get returns only keys that match the given names. This is a signed request.

PhraseApp API docs: http://docs.phraseapp.com/api/v1/translation_keys/#index

func (*KeysService) ListAll

func (s *KeysService) ListAll() ([]Key, error)

ListAll lists all keys for your current project.

PhraseApp API docs: http://docs.phraseapp.com/api/v1/translation_keys/#index

func (*KeysService) ListUntranslated

func (s *KeysService) ListUntranslated(l string) ([]Key, error)

ListUntranslated returns all untranslated keys for the given locale. Note: This will return 10,000 keys at most.

PhraseApp API docs: http://docs.phraseapp.com/api/v1/translation_keys/#untranslated

func (*KeysService) Tag

func (s *KeysService) Tag(ids []int, tags []string) error

Tag adds tags to the given keys. Existing tags for the given keys will not be removed. This is a signed request.

PhraseApp API docs: http://docs.phraseapp.com/api/v1/translation_keys/#tag

func (*KeysService) Translate

func (s *KeysService) Translate(key string) (*KeyTranslation, error)

Translate returns what I18n.translate(key) would return in Ruby in JSON format. This is to be able to provide data if the translation has not been used in a pure key-value-fashion, but to store an array or even a hash of its child items.

PhraseApp API docs: http://docs.phraseapp.com/api/v1/translation_keys/#translate

func (*KeysService) Update

func (s *KeysService) Update(k *Key) (*Key, error)

Update an existing key in the current project. This is a signed request.

PhraseApp API docs: http://docs.phraseapp.com/api/v1/translation_keys/#update

func (*KeysService) Upload

func (s *KeysService) Upload(u *UploadRequest) error

Upload a localization file to the current project. This will add new keys and their translations.

PhraseApp API docs: http://docs.phraseapp.com/api/v1/translation_keys/#upload

type Locale

type Locale struct {
	ID             int                          `json:"id"`
	Name           string                       `json:"name"`
	Code           string                       `json:"code"`
	CountryCode    string                       `json:"country_code"`
	Direction      string                       `json:"writing_direction"`
	Default        bool                         `json:"is_default"`
	Pluralizations map[string]map[string]string `json:"pluralizations"`
}

Locale represents a locale.

type LocaleProgress

type LocaleProgress struct {
	Locale   Locale   `json:"locale"`
	Progress Progress `json:"progress"`
}

LocaleProgress represents the translation progress with a Locale struct and a Progress struct.

type LocalesService

type LocalesService struct {
	// contains filtered or unexported fields
}

LocalesService provides access to the locales related functions in the PhraseApp API.

PhraseApp API docs: http://docs.phraseapp.com/api/v1/locales/

func (*LocalesService) Create

func (s *LocalesService) Create(name string) (*Locale, error)

Create a new locale in the current project.

PhraseApp API docs: http://docs.phraseapp.com/api/v1/locales/#create

func (*LocalesService) Download

func (s *LocalesService) Download(locale, format string, w io.Writer) error

Download translations for locale in a specific format. See http://docs.phraseapp.com/guides/formats/ for the list of all supported formats.

PhraseApp API docs: http://docs.phraseapp.com/api/v1/locales/#show

func (*LocalesService) ListAll

func (s *LocalesService) ListAll() ([]Locale, error)

ListAll returns list of existing locales in current project.

PhraseApp API docs: http://docs.phraseapp.com/api/v1/locales/#index

func (*LocalesService) MakeDefault

func (s *LocalesService) MakeDefault(name string) (*Locale, error)

MakeDefault promotes locale to be the default locale for the current project.

PhraseApp API docs: http://docs.phraseapp.com/api/v1/locales/#make_default

type Order

type Order struct {
	AmountInCents int `json:"amount_in_cents" url:"-"`

	// Name of the LSP you want to use for this order (can be "gengo" or "textmaster").
	LSP      string `json:"lsp" url:"lsp"`
	Code     string `json:"code" url:"-"`
	Currency string `json:"currency" url:"-"`

	// Give an optional message to be delivered to the translators.
	Message string `json:"message" url:"message,omitempty"`
	State   string `json:"state" url:"-"`

	// Quality level of the translations. Can be "standard" or "pro" for Gengo orders and "regular" or "premium" for TextMaster orders.
	TranslationType string `json:"translation_type" url:"translation_type"`
	ProgressPercent int    `json:"progress_percent" url:"-"`

	// Name of the source locale. This locale must already exist in your project. This usually is your default locale.
	SourceLocaleName string `json:"source_locale_name" url:"source_locale_name"`
	SourceLocaleCode string `json:"source_locale_code" url:"-"`

	// Name of the locale to translate your content into. This locale must already exist in your project.
	TargetLocaleNames []string `json:"target_locale_names" url:"target_locale_name[]"`
	TargetLocaleCodes []string `json:"target_locale_codes" url:"-"`

	// Name of a tag to limit the translations to. If none given, it is assumed that all existing keys should be translated.
	Tag           string `json:"tag_name" url:"tag_name,omitempty"`
	StyleguideURL string `json:"styleguide_url" url:"-"`
	Styleguide    string `json:"styleguide" url:"-"`

	// Identification code of the style guide to attach with this order.
	StyleguideCode string `json:"styleguide_code" url:"styleguide_code,omitempty"`

	// Enable unverifying translations upon delivery.
	UnverifyTranslationsUponDelivery bool `json:"unverify_translations_upon_delivery" url:"unverify_translations_upon_delivery,int,omitempty"`

	// Use this option to order translations for keys with unverified content in the selected target locales.
	IncludeUnverifiedTranslations bool `json:"include_unverified_translations" url:"include_unverified_translations,int,omitempty"`

	// Use this option to order translations for keys with untranslated content in the selected target locales.
	IncludeUntranslatedKeys bool `json:"include_untranslated_keys" url:"include_untranslated_keys,int,omitempty"`

	// Translations will be proofread by TextMaster to ensure consistency in vocabulary and style. Will cause additional costs! Only available for TextMaster!
	Quality bool `json:"quality" url:"quality,int,omitempty"`

	// Your project will be assigned a higher priority status, which decreases turnaround time by 30%. Will cause additional costs! Only available for TextMaster!
	Priority bool `json:"priority" url:"priority,int,omitempty"`

	// TextMaster provides you with an expert in the selected category. Will cause additional costs! Only available for TextMaster!
	Expertise bool `json:"expertise" url:"expertise,int,omitempty"`

	// Category ID to use (only required for orders through TextMaster).
	// http://docs.phraseapp.com/api/v1/translation_orders/#categories
	Category int `json:"category" url:"category,omitempty"`
}

Order represents a translation order.

type OrdersService

type OrdersService struct {
	// contains filtered or unexported fields
}

OrdersService provides access to the translation order related functions in the PhraseApp API.

PhraseApp API docs: http://docs.phraseapp.com/api/v1/translation_orders/

func (*OrdersService) Confirm

func (s *OrdersService) Confirm(code string) (*Order, error)

Confirm confirms an open order identified by the order code and starts the translation process. Valid billing information is required for this action. After confirming, the displayed amount will be charged. This is a signed request.

PhraseApp API docs: http://docs.phraseapp.com/api/v1/translation_orders/#confirm

func (*OrdersService) Create

func (s *OrdersService) Create(o *Order) (*Order, error)

Create a new order to confirm. This is a signed request.

PhraseApp API docs: http://docs.phraseapp.com/api/v1/translation_orders/#create

func (*OrdersService) Destroy

func (s *OrdersService) Destroy(code string) error

Destroy deletes an order (must not yet be confirmed). This is a signed request.

PhraseApp API docs: http://docs.phraseapp.com/api/v1/translation_orders/#destroy

func (*OrdersService) Get

func (s *OrdersService) Get(code string) (*Order, error)

Get details of the order identified by the order code. This is a signed request.

PhraseApp API docs: http://docs.phraseapp.com/api/v1/translation_orders/#show

func (*OrdersService) ListAll

func (s *OrdersService) ListAll() ([]Order, error)

ListAll gets a list of all orders in the current project. This is a signed request.

PhraseApp API docs: http://docs.phraseapp.com/api/v1/translation_orders/#index

type Progress

type Progress struct {
	TranslationsCount int `json:"translations_count"`
	TranslatedCount   int `json:"translated_count"`
	UnverifiedCount   int `json:"unverified_count"`
	UntranslatedCount int `json:"untranslated_count"`
}

Progress represents the progress of a translation.

type Project

type Project struct {
	ID   int    `json:"id"`
	Name string `json:"name"`
	Slug string `json:"slug"`
}

Project represents the project associated with the current auth token.

type ProjectsService

type ProjectsService struct {
	// contains filtered or unexported fields
}

ProjectsService provides access to the projects related functions in the PhraseApp API.

PhraseApp API docs: http://docs.phraseapp.com/api/v1/projects/

func (*ProjectsService) Current

func (s *ProjectsService) Current() (*Project, error)

Current gets details for the current project.

PhraseApp API docs: http://docs.phraseapp.com/api/v1/projects/

type RateLimit

type RateLimit struct {
	// Number of max requests allowed in the current time period.
	Limit int

	// Number of remaining requests in the current time period.
	Remaining int

	// Timestamp of end of current time period as UNIX timestamp.
	Reset time.Time
}

RateLimit represents the rate limits returned in the response.

type SessionsService

type SessionsService struct {
	// contains filtered or unexported fields
}

SessionsService provides access to the authentication related functions in the PhraseApp API.

PhraseApp API docs: http://docs.phraseapp.com/api/v1/authentication/

func (*SessionsService) CheckLogin

func (s *SessionsService) CheckLogin() (*User, error)

CheckLogin checks the validity of an auth_token and returns information of the current user.

PhraseApp API docs: http://docs.phraseapp.com/api/v1/authentication/#check_login

func (*SessionsService) Create

func (s *SessionsService) Create(email, password string) (string, error)

Create signs in a user identified by email and password.

PhraseApp API docs: http://docs.phraseapp.com/api/v1/authentication/#create

func (*SessionsService) Destroy

func (s *SessionsService) Destroy() error

Destroy logs the current user out.

PhraseApp API docs: http://docs.phraseapp.com/api/v1/authentication/#destroy

type Tag

type Tag struct {
	ID   int    `json:"id"`
	Name string `json:"name"`
}

Tag represents a tag.

type TagProgress

type TagProgress struct {
	Tag      Tag                       `json:"tag"`
	Progress map[string]LocaleProgress `json:"progress"`
}

TagProgress represents the translation progress of a Tag and a map of locales to Progress.

type TagsService

type TagsService struct {
	// contains filtered or unexported fields
}

TagsService provides access to the tags related functions in the PhraseApp API.

PhraseApp API docs: http://docs.phraseapp.com/api/v1/tags/

func (*TagsService) GetProgress

func (s *TagsService) GetProgress(id int) (*TagProgress, error)

GetProgress returns detailed information and progress for a tag.

PhraseApp API docs: http://docs.phraseapp.com/api/v1/tags/#show

func (*TagsService) ListAll

func (s *TagsService) ListAll() ([]Tag, error)

ListAll returns a list of all tags in the current project.

PhraseApp API docs: http://docs.phraseapp.com/api/v1/tags/#index

type Translation

type Translation struct {
	ID      int    `json:"id" url:"-"`
	Content string `json:"content" url:"content"`

	// A plural suffix (only required when the key is pluralized).
	PluralSuffix string   `json:"plural_suffix" url:"plural_suffix"`
	Placeholders []string `json:"placeholders" url:"-"`
	Unverified   bool     `json:"unverified" url:"-"`

	// Whether the translation should be excluded from file downloads.
	ExcludedFromExport bool `json:"excluded_from_export" url:"excluded_from_export,int,omitempty"`
	Key                Key  `json:"translation_key" url:"-"`
}

Translation represents a translation stored in PhraseApp.

type TranslationsService

type TranslationsService struct {
	// contains filtered or unexported fields
}

TranslationsService provides access to the translation related functions in the PhraseApp API.

PhraseApp API docs: http://docs.phraseapp.com/api/v1/translations/

func (*TranslationsService) Download

Download translations as localization file. This call is rate limited.

PhraseApp API docs: http://docs.phraseapp.com/api/v1/translations/#download

func (*TranslationsService) Get

func (s *TranslationsService) Get(l string, t *time.Time) ([]Translation, error)

Get lists all translations for a locale.

PhraseApp API docs: http://docs.phraseapp.com/api/v1/translations/#index

func (*TranslationsService) GetByKeys

func (s *TranslationsService) GetByKeys(l string, keys []string) ([]Translation, error)

GetByKeys fetches translations for a locale and a list of keys.

PhraseApp API docs: http://docs.phraseapp.com/api/v1/translations/#fetch_list

func (*TranslationsService) ListAll

func (s *TranslationsService) ListAll() (map[string][]Translation, error)

ListAll lists all translations for all locale.

PhraseApp API docs: http://docs.phraseapp.com/api/v1/translations/#index

func (*TranslationsService) Update

func (s *TranslationsService) Update(locale, key string, t *Translation, skipVerification, disallowUpdate bool) (*Translation, error)

Update saves a translation for a given locale.

PhraseApp API docs: http://docs.phraseapp.com/api/v1/translations/#store

type UploadRequest

type UploadRequest struct {
	Filename           string   `url:"filename"`
	FileContent        string   `url:"file_content"`
	Tags               []string `url:"tags[],omitempty"`
	Locale             string   `url:"locale_name,omitempty"`
	Format             string   `url:"file_format,omitempty"`
	UpdateTranslations bool     `url:"update_translations,int,omitempty"`
	SkipUnverification bool     `url:"skip_unverification,int,omitempty"`
	SkipUploadTags     bool     `url:"skip_upload_tags,int,omitempty"`
	ConvertEmoji       bool     `url:"convert_emoji,int,omitempty"`
}

UploadRequest represents a request to the Upload API call.

type User

type User struct {
	ID       int    `json:"id"`
	Username string `json:"username"`
	Email    string `json:"email"`
	Name     string `json:"name"`
	Role     string `json:"role_name"`
}

User represents a user account in Phrase.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL