Skip to content

Commit aebf87c

Browse files
author
Jérémie Parker
committed
docs(README): add doc about contributor management
1 parent 6283dd7 commit aebf87c

File tree

1 file changed

+181
-59
lines changed

1 file changed

+181
-59
lines changed

‎README.md‎

Lines changed: 181 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -26,23 +26,28 @@ Add a `.gitporc` with the followings:
2626
This package provide a CLI powered by [Inquirer](https://github.com/sboudrias/Inquirer.js)
2727

2828
```
29-
? What would you like to do
29+
? What would you like to do: (Use arrow keys)
3030
❯ View Project Details
3131
Update Code (POEditor → GitHub)
3232
Update POEditor (GitHub → POEditor)
3333
Remove default Translations
34+
Manage contributors
3435
```
36+
3537
You'll be able to trigger webhooks from POEditor to run associated actions.
3638

3739
**Remove default Translations** is a utility to which you need to pass a JSON file path and that will remove values that are the same as the keys.
3840
eg:
41+
3942
```json
4043
{
4144
"hello world": "hello world",
4245
"this key will not be cleaned": "because the value is different"
4346
}
4447
```
48+
4549
will be turned into
50+
4651
```json
4752
{
4853
"hello world": "",
@@ -52,20 +57,25 @@ will be turned into
5257

5358
As we use gettext based i18n solution and english fallback in our transaltion files, this help remove english fallbacks from our output files when we need to reprocess them.
5459

60+
---
61+
5562
### Programatical Usage
5663

5764
```js
5865
const {
66+
addContributor,
5967
cleanTranslationJSON,
6068
importNewTerms,
69+
listContributors,
6170
listProjectLanguages,
6271
listProjects,
72+
removeContributor,
6373
synchronizeTerms,
6474
updateTranslations,
65-
viewProject
75+
viewProject,
6676
} = require('gitpo')
6777

68-
const languages = await listProjectLanguages(projectId).run()
78+
const languages = await listProjectLanguages(projectId)
6979
console.log(languages)
7080

7181
// [
@@ -80,64 +90,103 @@ console.log(languages)
8090
// percentage: 70.44,
8191
// updated: '2017-11-16T11:33:54+0000' },
8292
// ]
83-
8493
```
8594

95+
---
96+
8697
### Reference
8798

8899
All functions are async and return a Promise.
89-
#### cleanTranslationJSON(file, override)
90100

91-
| Type | Param | Description |
92-
| ---- | ----- | ----------- |
93-
| *String* | `file` | is a path to the file to clean |
94-
| *Bool* | `override` | should override the existing file or not, default to `false` |
101+
#### Utility
102+
103+
##### cleanTranslationJSON(file, override)
104+
105+
| Type | Param | Description |
106+
| -------- | ---------- | ------------------------------------------------------------ |
107+
| _String_ | `file` | is a path to the file to clean |
108+
| _Bool_ | `override` | should override the existing file or not, default to `false` |
95109

96110
Clean JSON translation file of any default value:
111+
97112
```json
98113
{
99114
"hello world": "hello world",
100115
"this key will not be cleaned": "because the value is different"
101116
}
102117
```
118+
103119
will be turned into
120+
104121
```json
105122
{
106123
"hello world": "",
107124
"this key will not be cleaned": "because the value is different"
108125
}
109126
```
127+
110128
It will create a file next to the input if override is set to false, eg: `en.json` → `en.clean.json`)
111129

112-
#### importNewTerms(projectId)
130+
#### Webhooks
131+
132+
Manual trigger of webhooks to update POEditor from a Github repository & vice versa.
113133

114-
| Type | Param | Description |
115-
| ---- | ----- | ----------- |
116-
| *Number* | `projectId` | The POEditor project id |
134+
##### importNewTerms(projectId)
135+
136+
| Type | Param | Description |
137+
| -------- | ----------- | ----------------------- |
138+
| _Number_ | `projectId` | The POEditor project id |
117139

118140
Run the `import_translations` webhook on the given project (see: [POEdtor Webhook Documentation](https://poeditor.com/help/how_to_use_the_github_webhook))
119141

120-
#### listProjectLanguages(projectId)
142+
#### synchronizeTerms(projectId)
143+
144+
| Type | Param | Description |
145+
| -------- | ----------- | ----------------------- |
146+
| _Number_ | `projectId` | The POEditor project id |
147+
148+
Run the `sync_terms_and_translations` webhook on the given project (see: [POEdtor Webhook Documentation](https://poeditor.com/help/how_to_use_the_github_webhook))
149+
150+
#### updateTranslations(projectId, languages)
151+
152+
| Type | Param | Description |
153+
| -------- | ----------- | ----------------------- |
154+
| _Number_ | `projectId` | The POEditor project id |
155+
| _Array_ | `languages` | List of language code |
156+
157+
Run the `export_terms_and_translations` webhook on the given project and languages (see: [POEdtor Webhook Documentation](https://poeditor.com/help/how_to_use_the_github_webhook))
158+
159+
:warning: To complete this action, one call per language will be made.
160+
161+
#### API
162+
163+
##### listProjectLanguages(projectId)
121164

122-
| Type | Param | Description |
123-
| ---- | ----- | ----------- |
124-
| *Number* | `projectId` | The POEditor project id |
165+
| Type | Param | Description |
166+
| -------- | ----------- | ----------------------- |
167+
| _Number_ | `projectId` | The POEditor project id |
125168

126169
List languages for a given project (see: [POEdtor API Documentation](https://poeditor.com/docs/api#languages_list))
127170

128171
Example of value returned on `Promise.resolve`
129172

130-
```js
131-
[ { name: 'English',
132-
code: 'en',
133-
translations: 2067,
134-
percentage: 100,
135-
updated: '2017-11-16T09:14:45+0000' },
136-
{ name: 'French',
137-
code: 'fr',
138-
translations: 1456,
139-
percentage: 70.44,
140-
updated: '2017-11-16T11:33:54+0000' } ]
173+
```json
174+
[
175+
{
176+
"name": "English",
177+
"code": "en",
178+
"translations": 2067,
179+
"percentage": 100,
180+
"updated": "2017-11-16T09:14:45+0000"
181+
},
182+
{
183+
"name": "French",
184+
"code": "fr",
185+
"translations": 1456,
186+
"percentage": 70.44,
187+
"updated": "2017-11-16T11:33:54+0000"
188+
}
189+
]
141190
```
142191

143192
#### listProjects()
@@ -146,54 +195,127 @@ List projects you can access (see: [POEdtor API Documentation](https://poeditor.
146195

147196
Example of value returned on `Promise.resolve`
148197

149-
```js
150-
[ { id: 1111,
151-
name: 'VizEat.com',
152-
public: 0,
153-
open: 0,
154-
created: '2014-06-06T12:00:00+0000' } ]
198+
```json
199+
[
200+
{
201+
"id": 1111,
202+
"name": "Project Name",
203+
"public": 0,
204+
"open": 0,
205+
"created": "2014-06-06T12:00:00+0000"
206+
}
207+
]
155208
```
156209

157-
#### synchronizeTerms(projectId)
210+
#### viewProject(projectId)
158211

159-
| Type | Param | Description |
160-
| ---- | ----- | ----------- |
161-
| *Number* | `projectId` | The POEditor project id |
212+
| Type | Param | Description |
213+
| -------- | ----------- | ----------------------- |
214+
| _Number_ | `projectId` | The POEditor project id |
162215

163-
Run the `sync_terms_and_translations` webhook on the given project (see: [POEdtor Webhook Documentation](https://poeditor.com/help/how_to_use_the_github_webhook))
216+
Get the details of a given project (see: [POEdtor API Documentation](https://poeditor.com/docs/api#projects_view))
164217

165-
#### updateTranslations(projectId, languages)
218+
Example of value returned on `Promise.resolve`
166219

167-
| Type | Param | Description |
168-
| ---- | ----- | ----------- |
169-
| *Number* | `projectId` | The POEditor project id |
170-
| *Array* | `languages` | List of language code |
220+
```json
221+
[
222+
{
223+
"id": 1111,
224+
"name": "Project Name",
225+
"public": 0,
226+
"open": 0,
227+
"created": "2014-06-06T12:00:00+0000"
228+
}
229+
]
230+
```
171231

172-
Run the `export_terms_and_translations` webhook on the given project and languages (see: [POEdtor Webhook Documentation](https://poeditor.com/help/how_to_use_the_github_webhook))
232+
#### listContributors()
173233

174-
:warning: To complete this action, one call per language will be made.
234+
List contributors to your projects
175235

236+
Example of value returned on `Promise.resolve`
176237

177-
#### viewProject(projectId)
238+
```json
239+
[
240+
{
241+
"name": "Alice",
242+
"email": "alice@example.com",
243+
"permissions": [
244+
{
245+
"project": {
246+
"id": 1111,
247+
"name": "Project Name"
248+
},
249+
"type": "administrator"
250+
}
251+
],
252+
"created": "2014-06-06T12:00:00+0000"
253+
},
254+
{
255+
"name": "Bob",
256+
"email": "bob@example.com",
257+
"permissions": [
258+
{
259+
"project": {
260+
"id": 1111,
261+
"name": "Project Name"
262+
},
263+
"type": "contributor",
264+
"languages": ["fr", "en"]
265+
}
266+
],
267+
"created": "2014-06-06T12:00:00+0000"
268+
}
269+
]
270+
```
178271

179-
| Type | Param | Description |
180-
| ---- | ----- | ----------- |
181-
| *Number* | `projectId` | The POEditor project id |
272+
#### addContributors(email, fullname, projects, languages)
182273

183-
Get the details of a given project (see: [POEdtor API Documentation](https://poeditor.com/docs/api#projects_view))
274+
| Type | Param | Description |
275+
| -------- | ----------- | --------------------------- |
276+
| _String_ | `email` | Contributor's email address |
277+
| _String_ | `fullname` | Contributor's fullname |
278+
| _Array_ | `projects` | List of POEditor project id |
279+
| _Array_ | `languages` | List of language code |
184280

185-
Example of value returned on `Promise.resolve`
281+
Add the given contributor to the list of project / language.
186282

187-
```js
188-
[ { id: 1111,
189-
name: 'VizEat.com',
190-
public: 0,
191-
open: 0,
192-
created: '2014-06-06T12:00:00+0000' } ]
193-
```
283+
:warning: **NOTE:** An assumption is made here that may require some changes to support a more general use case:
284+
285+
- All projects have all the same languages
286+
_or_
287+
- Poeditor API will ignore addition to non existing languages for a given project
288+
289+
**These cases where not tested**
290+
291+
:warning: An API call is made for every language in every project.
292+
293+
#### removeContributors(email, projects, languages)
294+
295+
| Type | Param | Description |
296+
| -------- | ----------- | --------------------------- |
297+
| _String_ | `email` | Contributor's email address |
298+
| _Array_ | `projects` | List of POEditor project id |
299+
| _Array_ | `languages` | List of language code |
300+
301+
Remove the given contributor from the list of project / language.
302+
303+
:warning: **NOTE:** An assumption is made here that may require some changes to support a more general use case:
304+
305+
- All projects have all the same languages
306+
_or_
307+
- Poeditor API will ignore addition to non existing languages for a given project
308+
309+
**These cases where not tested**
310+
311+
:warning: An API call is made for every language in every project.
312+
313+
---
194314

195315
## Contributing
316+
196317
Format code using the provided `yarn fmt` command
197318

198319
## License
320+
199321
MIT

0 commit comments

Comments
 (0)